pythonnative 0.35.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/components/ComponentManager.kt

@@ -0,0 +1,213 @@
+package com.pythonnative.runtime.components
+
+import android.content.Context
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.animation.PNAnimator
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.ViewRecord
+import com.pythonnative.runtime.bridge.present
+import org.json.JSONArray
+import org.json.JSONObject
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/**
+ * Base class for one element type's native implementation.
+ *
+ * Subclasses implement [createView] (construct the widget) and
+ * [applyProps] (apply visual props); the base class owns frame
+ * application, intrinsic measurement, child management, and the
+ * animation hooks. All geometry crossing this API is in dp.
+ */
+abstract class ComponentManager {
+    /** Construct the widget for `tag`; `props` may be consulted for creation-time choices. */
+    abstract fun createView(context: Context, tag: Long, props: JSONObject): View
+
+    /**
+     * Apply `props` to `view`. `initial` is `true` for the create op;
+     * on updates `props` holds only the changed keys (JSON null means
+     * removed). The merged props are always available via [propsOf].
+     */
+    open fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        ViewStyler.apply(view, props)
+    }
+
+    /** Apply changed props (the `u` op). */
+    fun update(view: View, changed: JSONObject) = applyProps(view, changed, false)
+
+    /** Ensure `child` sits at `index` under `parent` (move-aware, clamped). */
+    open fun insertChild(parent: View, child: View, index: Int) {
+        val group = parent as? ViewGroup ?: return
+        ViewChildren.insert(group, child, index)
+    }
+
+    /** Detach `child` from `parent` without destroying it. */
+    open fun removeChild(parent: View, child: View) {
+        (parent as? ViewGroup)?.removeView(child)
+    }
+
+    /** Release resources and detach from the parent. */
+    open fun destroy(view: View) {
+        try {
+            teardown(view)
+        } catch (e: Exception) {
+            Log.d(PNBridge.TAG, "teardown failed for ${view.javaClass.simpleName}", e)
+        }
+        (view.parent as? ViewGroup)?.removeView(view)
+    }
+
+    /** Subclass hook for extra cleanup before the view is released. */
+    protected open fun teardown(view: View) {}
+
+    /**
+     * Position `view` inside its parent's `FrameLayout` via margin layout
+     * params. Non-finite values are clamped; sizes are never negative.
+     */
+    open fun setFrame(view: View, x: Double, y: Double, width: Double, height: Double) {
+        val pxX = px(finite(x))
+        val pxY = px(finite(y))
+        val pxW = max(0, px(finite(width)))
+        val pxH = max(0, px(finite(height)))
+        val lp = view.layoutParams
+        val params: ViewGroup.LayoutParams = if (lp == null) {
+            FrameLayout.LayoutParams(pxW, pxH)
+        } else {
+            lp.width = pxW
+            lp.height = pxH
+            lp
+        }
+        if (params is ViewGroup.MarginLayoutParams) {
+            params.leftMargin = pxX
+            params.topMargin = pxY
+            params.rightMargin = 0
+            params.bottomMargin = 0
+        }
+        view.layoutParams = params
+        val record = recordOf(view)
+        if (record != null) {
+            record.frame = doubleArrayOf(x, y, width, height)
+            if (record.props.present("hit_slop") || record.state["hit_slop_active"] == true) {
+                ViewStyler.updateHitSlop(view)
+            }
+        }
+    }
+
+    /**
+     * Natural size of `view` under the constraints, in dp. Either
+     * constraint may be `1e6` or infinite meaning unconstrained.
+     */
+    open fun measure(view: View, maxWidth: Double, maxHeight: Double): FloatArray {
+        val density = PNBridge.density()
+        val wSpec = measureSpec(maxWidth, density)
+        val hSpec = measureSpec(maxHeight, density)
+        view.measure(wSpec, hSpec)
+        return floatArrayOf(view.measuredWidth / density, view.measuredHeight / density)
+    }
+
+    /** Run an imperative command; unknown names return `null`. */
+    open fun command(view: View, name: String, args: JSONObject): Any? = null
+
+    /** Apply one Python-driven animation frame immediately. */
+    open fun setAnimatedProperty(view: View, prop: String, value: Any?) {
+        PNAnimator.setProperty(view, prop, value)
+    }
+
+    /** Start a natively driven animation; `false` asks Python to tick it instead. */
+    open fun startAnimation(view: View, id: Long, prop: String, spec: JSONObject): Boolean =
+        PNAnimator.start(view, id, prop, spec)
+
+    /** Cancel a native animation and return the presentation value, if readable. */
+    open fun cancelAnimation(view: View, id: Long): Any? = PNAnimator.cancel(id)
+
+    // ------------------------------------------------------------------
+    // Helpers for subclasses
+    // ------------------------------------------------------------------
+
+    /** The registry record for `view`, or `null` for foreign views. */
+    protected fun recordOf(view: View): ViewRecord? = PNBridge.registry.recordFor(view)
+
+    /** Merged props for `view` (empty for foreign views). */
+    protected fun propsOf(view: View): JSONObject = recordOf(view)?.props ?: JSONObject()
+
+    /** Manager-private state map for `view`. */
+    protected fun stateOf(view: View): MutableMap<String, Any?> = recordOf(view)?.state ?: HashMap()
+
+    /** Dispatch event `name` with positional `args` for `view`'s tag. */
+    protected fun fire(view: View, name: String, vararg args: Any?): Boolean = PNEvents.fire(view, name, *args)
+
+    /** Dispatch event `name` and return Python's (JSON) reply. */
+    protected fun fireForResult(view: View, name: String, vararg args: Any?): String? =
+        PNEvents.fireForResult(view, name, *args)
+
+    /** Whether the element wired a callback named `name`. */
+    protected fun hasEvent(view: View, name: String): Boolean = recordOf(view)?.hasEvent(name) ?: false
+
+    /** dp to whole pixels. */
+    protected fun px(dp: Double): Int = (dp * PNBridge.density()).roundToInt()
+
+    /** dp to pixels as a float. */
+    protected fun pxF(dp: Double): Float = (dp * PNBridge.density()).toFloat()
+
+    /** pixels to dp. */
+    protected fun dp(px: Number): Double = px.toDouble() / PNBridge.density()
+
+    private fun finite(v: Double): Double = if (v.isNaN() || v.isInfinite()) 0.0 else v
+
+    private fun measureSpec(limit: Double, density: Float): Int {
+        if (limit.isNaN() || limit.isInfinite() || limit >= 1e6) {
+            return View.MeasureSpec.makeMeasureSpec(0, View.MeasureSpec.UNSPECIFIED)
+        }
+        val px = min((max(0.0, limit) * density).toInt(), (1 shl 29))
+        return View.MeasureSpec.makeMeasureSpec(px, View.MeasureSpec.AT_MOST)
+    }
+}
+
+/** Move-aware indexed insertion into any `ViewGroup`. */
+object ViewChildren {
+    fun insert(parent: ViewGroup, child: View, index: Int) {
+        val current = child.parent as? ViewGroup
+        if (current === parent) {
+            val currentIndex = parent.indexOfChild(child)
+            val target = max(0, min(index, parent.childCount - 1))
+            if (currentIndex == target) return
+            parent.removeView(child)
+            parent.addView(child, max(0, min(target, parent.childCount)))
+            return
+        }
+        current?.removeView(child)
+        if (child.layoutParams == null) {
+            child.layoutParams = FrameLayout.LayoutParams(0, 0)
+        }
+        parent.addView(child, max(0, min(index, parent.childCount)))
+    }
+}
+
+/** Event dispatch keyed by view identity. */
+object PNEvents {
+    /** Dispatch `name` for `view` with positional `args`; `false` when the view is unknown. */
+    fun fire(view: View, name: String, vararg args: Any?): Boolean {
+        val tag = PNBridge.registry.tagOf(view) ?: return false
+        fireTag(tag, name, JsonUtil.args(*args))
+        return true
+    }
+
+    /** Dispatch `name` for `view` and return Python's JSON reply. */
+    fun fireForResult(view: View, name: String, vararg args: Any?): String? {
+        val tag = PNBridge.registry.tagOf(view) ?: return null
+        return fireTag(tag, name, JsonUtil.args(*args))
+    }
+
+    /** Dispatch `name` for `tag` with an already built argument array. */
+    fun fireTag(tag: Long, name: String, args: JSONArray): String? =
+        PNBridge.callPython("event", tag, name, args.toString())
+}
+
+/** Fallback for unknown element types: an empty container that hosts children. */
+class PlaceholderManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View = FrameLayout(context)
+}

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/components/ContainerManagers.kt

@@ -0,0 +1,69 @@
+package com.pythonnative.runtime.components
+
+import android.content.Context
+import android.view.View
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.modules.ModuleEvents
+import com.pythonnative.runtime.views.PNFrameLayout
+import org.json.JSONObject
+import kotlin.math.max
+
+/**
+ * Flex container (shared by `View`, `Column`, and `Row`): a bare
+ * [PNFrameLayout]. All flex semantics are computed by the Python layout
+ * engine and applied through `setFrame`; the container is just a
+ * positioning surface with `pointer_events` interception.
+ */
+open class ViewManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View = PNFrameLayout(context)
+}
+
+/** Empty layout placeholder used as a flexible gap. */
+class SpacerManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View = View(context)
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        // Spacers carry no visual props of their own.
+    }
+}
+
+/** Safe-area container: a flex container with `fitsSystemWindows`. */
+class SafeAreaViewManager : ViewManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val view = PNFrameLayout(context)
+        view.fitsSystemWindows = true
+        return view
+    }
+}
+
+/**
+ * Vanilla container that publishes the keyboard height (from window
+ * insets) as a `Host` module `keyboard` event so the Python-side
+ * component can compute its offset.
+ */
+class KeyboardAvoidingViewManager : ViewManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val view = PNFrameLayout(context)
+        ViewCompat.setOnApplyWindowInsetsListener(view) { v, insets ->
+            publishKeyboard(v, insets)
+            insets
+        }
+        view.addOnLayoutChangeListener { v, _, _, _, _, _, _, _, _ ->
+            ViewCompat.getRootWindowInsets(v)?.let { publishKeyboard(v, it) }
+        }
+        return view
+    }
+
+    private fun publishKeyboard(view: View, insets: WindowInsetsCompat) {
+        val density = PNBridge.density()
+        val ime = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom
+        val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars()).bottom
+        val height = max(0, ime - bars) / density
+        val last = stateOf(view)["keyboard_height"] as? Double
+        if (last != null && last == height.toDouble()) return
+        stateOf(view)["keyboard_height"] = height.toDouble()
+        ModuleEvents.emit("Host", "keyboard", JSONObject().put("height", height.toDouble()))
+    }
+}

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/components/ControlManagers.kt

@@ -0,0 +1,186 @@
+package com.pythonnative.runtime.components
+
+import android.content.Context
+import android.content.res.ColorStateList
+import android.view.View
+import android.widget.CheckBox
+import android.widget.CompoundButton
+import android.widget.ProgressBar
+import android.widget.SeekBar
+import android.widget.Switch
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.num
+import com.pythonnative.runtime.bridge.str
+import com.pythonnative.runtime.bridge.value
+import org.json.JSONObject
+
+/** Base for `CompoundButton` widgets: `on_change` wiring with a suppress guard. */
+abstract class CheckedManager : ComponentManager() {
+    protected fun bindChecked(button: CompoundButton) {
+        button.setOnCheckedChangeListener { b, checked ->
+            if (stateOf(b)["suppress"] == true) return@setOnCheckedChangeListener
+            fire(b, "on_change", checked)
+        }
+    }
+}
+
+/** `Switch` element. */
+class SwitchManager : CheckedManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val sw = Switch(context)
+        bindChecked(sw)
+        return sw
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val sw = view as Switch
+        if (props.has("value")) {
+            val state = stateOf(sw)
+            state["suppress"] = true
+            try {
+                sw.isChecked = JsonUtil.truthy(props.value("value"))
+            } finally {
+                state["suppress"] = false
+            }
+        }
+        if (props.has("disabled")) sw.isEnabled = !JsonUtil.truthy(props.value("disabled"))
+        if (props.has("enabled")) sw.isEnabled = JsonUtil.truthy(props.value("enabled"))
+        PNColor.parse(props.value("on_tint_color") ?: props.value("tint_color"))?.let {
+            sw.thumbTintList = ColorStateList(
+                arrayOf(intArrayOf(android.R.attr.state_checked), intArrayOf()),
+                intArrayOf(it, 0xFFFAFAFA.toInt()),
+            )
+            sw.trackTintList = ColorStateList(
+                arrayOf(intArrayOf(android.R.attr.state_checked), intArrayOf()),
+                intArrayOf(PNColor.withAlpha(it, 0.5), 0x61000000),
+            )
+        }
+        PNColor.parse(props.value("thumb_color"))?.let { sw.thumbTintList = ColorStateList.valueOf(it) }
+        ViewStyler.applyAccessibility(sw, props)
+    }
+}
+
+/** `Checkbox` element with an optional inline label. */
+class CheckboxManager : CheckedManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val cb = CheckBox(context)
+        bindChecked(cb)
+        return cb
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val cb = view as CheckBox
+        if (props.has("label")) cb.text = props.str("label") ?: ""
+        if (props.has("value")) {
+            val state = stateOf(cb)
+            state["suppress"] = true
+            try {
+                cb.isChecked = JsonUtil.truthy(props.value("value"))
+            } finally {
+                state["suppress"] = false
+            }
+        }
+        if (props.has("disabled")) cb.isEnabled = !JsonUtil.truthy(props.value("disabled"))
+        PNColor.parse(props.value("color"))?.let { cb.buttonTintList = ColorStateList.valueOf(it) }
+        ViewStyler.applyAccessibility(cb, props)
+    }
+}
+
+/** `ProgressBar` element: a horizontal determinate bar with a 0..1 `value`. */
+class ProgressBarManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val pb = ProgressBar(context, null, android.R.attr.progressBarStyleHorizontal)
+        pb.max = 1000
+        return pb
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val pb = view as ProgressBar
+        props.num("value")?.let { pb.progress = (it.coerceIn(0.0, 1.0) * 1000).toInt() }
+        PNColor.parse(props.value("color"))?.let { pb.progressTintList = ColorStateList.valueOf(it) }
+        PNColor.parse(props.value("track_color"))?.let {
+            val track = ColorStateList.valueOf(it)
+            pb.progressBackgroundTintList = track
+            pb.secondaryProgressTintList = track
+        }
+        if (props.has("indeterminate")) pb.isIndeterminate = JsonUtil.truthy(props.value("indeterminate"))
+        ViewStyler.apply(pb, props)
+    }
+}
+
+/** `ActivityIndicator` element: an indeterminate spinner. */
+class ActivityIndicatorManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View = ProgressBar(context)
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val pb = view as ProgressBar
+        if (props.has("animating")) {
+            pb.visibility = if (JsonUtil.truthy(props.value("animating"))) View.VISIBLE else View.GONE
+        }
+        if (props.has("hides_when_stopped") && !JsonUtil.truthy(props.value("hides_when_stopped"))) {
+            pb.visibility = View.VISIBLE
+        }
+        PNColor.parse(props.value("color"))?.let { pb.indeterminateTintList = ColorStateList.valueOf(it) }
+        props.str("size")?.let {
+            // The framework ProgressBar has no runtime size switch; scale "large".
+            val scale = if (it == "large") 1.5f else 1f
+            pb.scaleX = scale
+            pb.scaleY = scale
+        }
+        ViewStyler.apply(pb, props)
+    }
+}
+
+/** `Slider` element: a `SeekBar` mapped onto `min_value..max_value`. */
+class SliderManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val sb = SeekBar(context)
+        sb.max = 1000
+        sb.setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
+            override fun onProgressChanged(seekBar: SeekBar, progress: Int, fromUser: Boolean) {
+                if (!fromUser) return
+                fire(seekBar, "on_change", valueFor(seekBar, progress))
+            }
+
+            override fun onStartTrackingTouch(seekBar: SeekBar) {
+                fire(seekBar, "on_sliding_start", valueFor(seekBar, seekBar.progress))
+            }
+
+            override fun onStopTrackingTouch(seekBar: SeekBar) {
+                fire(seekBar, "on_sliding_complete", valueFor(seekBar, seekBar.progress))
+            }
+        })
+        return sb
+    }
+
+    private fun range(view: View): Pair<Double, Double> {
+        val merged = propsOf(view)
+        val mn = merged.num("min_value") ?: merged.num("minimum_value") ?: 0.0
+        val mx = merged.num("max_value") ?: merged.num("maximum_value") ?: 1.0
+        return Pair(mn, mx)
+    }
+
+    private fun valueFor(view: View, progress: Int): Double {
+        val (mn, mx) = range(view)
+        val span = if (mx != mn) mx - mn else 1.0
+        var value = mn + (progress / 1000.0) * span
+        propsOf(view).num("step")?.takeIf { it > 0 }?.let { step ->
+            value = mn + Math.round((value - mn) / step) * step
+        }
+        return value
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val sb = view as SeekBar
+        val (mn, mx) = range(sb)
+        val span = if (mx != mn) mx - mn else 1.0
+        props.num("value")?.let { sb.progress = (((it - mn) / span) * 1000).toInt().coerceIn(0, 1000) }
+        if (props.has("disabled")) sb.isEnabled = !JsonUtil.truthy(props.value("disabled"))
+        PNColor.parse(props.value("minimum_track_tint_color") ?: props.value("tint_color"))?.let {
+            sb.progressTintList = ColorStateList.valueOf(it)
+        }
+        PNColor.parse(props.value("maximum_track_tint_color"))?.let { sb.progressBackgroundTintList = ColorStateList.valueOf(it) }
+        PNColor.parse(props.value("thumb_tint_color"))?.let { sb.thumbTintList = ColorStateList.valueOf(it) }
+        ViewStyler.applyAccessibility(sb, props)
+    }
+}

pythonnative/templates/android_template/pythonnative/src/main/java/com/pythonnative/runtime/components/DatePickerManager.kt

@@ -0,0 +1,123 @@
+package com.pythonnative.runtime.components
+
+import android.app.DatePickerDialog
+import android.app.TimePickerDialog
+import android.content.Context
+import android.view.View
+import android.widget.Button
+import com.pythonnative.runtime.bridge.PNLog
+import com.pythonnative.runtime.bridge.str
+import com.pythonnative.runtime.bridge.value
+import org.json.JSONObject
+import java.text.SimpleDateFormat
+import java.util.Calendar
+import java.util.Locale
+
+/**
+ * `DatePicker` element: a trigger `Button` opening the native
+ * `DatePickerDialog` (`mode` `"date"`), `TimePickerDialog` (`"time"`),
+ * or a chained date-then-time flow (`"datetime"`). Values are ISO
+ * strings; the confirmed value is reported through `on_change`.
+ */
+class DatePickerManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val btn = Button(context)
+        btn.isAllCaps = false
+        btn.setOnClickListener { v ->
+            if (propsOf(v).value("enabled") == false) return@setOnClickListener
+            openDialog(v as Button)
+        }
+        return btn
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val btn = view as Button
+        if (props.has("enabled")) btn.isEnabled = props.value("enabled") != false
+        if (props.has("value") || props.has("mode") || initial) refreshLabel(btn)
+        ViewStyler.applyAccessibility(btn, props)
+    }
+
+    private fun mode(btn: Button): String = propsOf(btn).str("mode") ?: "date"
+
+    private fun refreshLabel(btn: Button) {
+        val value = propsOf(btn).str("value")
+        btn.text = if (!value.isNullOrEmpty()) value else PLACEHOLDERS[mode(btn)] ?: "Select"
+    }
+
+    private fun openDialog(btn: Button) {
+        val mode = mode(btn)
+        val cal = parse(propsOf(btn).str("value"), mode)
+        when (mode) {
+            "time" -> openTime(btn, cal)
+            "datetime" -> openDate(btn, cal, thenTime = true)
+            else -> openDate(btn, cal, thenTime = false)
+        }
+    }
+
+    private fun openDate(btn: Button, cal: Calendar, thenTime: Boolean) {
+        val dialog = DatePickerDialog(
+            btn.context,
+            { _, year, month, day ->
+                cal.set(Calendar.YEAR, year)
+                cal.set(Calendar.MONTH, month)
+                cal.set(Calendar.DAY_OF_MONTH, day)
+                if (thenTime) openTime(btn, cal) else commit(btn, cal)
+            },
+            cal.get(Calendar.YEAR),
+            cal.get(Calendar.MONTH),
+            cal.get(Calendar.DAY_OF_MONTH),
+        )
+        try {
+            val merged = propsOf(btn)
+            merged.str("minimum")?.takeIf { it.isNotEmpty() }?.let { dialog.datePicker.minDate = parse(it, mode(btn)).timeInMillis }
+            merged.str("maximum")?.takeIf { it.isNotEmpty() }?.let { dialog.datePicker.maxDate = parse(it, mode(btn)).timeInMillis }
+        } catch (e: Exception) {
+            PNLog.swallowed("DatePickerManager.minMax", e)
+        }
+        dialog.show()
+    }
+
+    private fun openTime(btn: Button, cal: Calendar) {
+        TimePickerDialog(
+            btn.context,
+            { _, hour, minute ->
+                cal.set(Calendar.HOUR_OF_DAY, hour)
+                cal.set(Calendar.MINUTE, minute)
+                commit(btn, cal)
+            },
+            cal.get(Calendar.HOUR_OF_DAY),
+            cal.get(Calendar.MINUTE),
+            true,
+        ).show()
+    }
+
+    private fun format(mode: String): SimpleDateFormat = SimpleDateFormat(PATTERNS[mode] ?: PATTERNS["date"]!!, Locale.US)
+
+    private fun parse(value: String?, mode: String): Calendar {
+        val cal = Calendar.getInstance()
+        if (!value.isNullOrEmpty()) {
+            try {
+                format(mode).parse(value)?.let { cal.time = it }
+            } catch (e: Exception) {
+                PNLog.swallowed("DatePickerManager.parse", e)
+            }
+        }
+        return cal
+    }
+
+    private fun commit(btn: Button, cal: Calendar) {
+        val iso = try {
+            format(mode(btn)).format(cal.time)
+        } catch (e: Exception) {
+            return
+        }
+        propsOf(btn).put("value", iso)
+        btn.text = iso
+        fire(btn, "on_change", iso)
+    }
+
+    private companion object {
+        val PATTERNS = mapOf("date" to "yyyy-MM-dd", "time" to "HH:mm", "datetime" to "yyyy-MM-dd'T'HH:mm")
+        val PLACEHOLDERS = mapOf("date" to "Select date", "time" to "Select time", "datetime" to "Select date & time")
+    }
+}