pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/android/src/main/java/com/pythonnative/runtime/screens/PNScreenFragment.kt

@@ -0,0 +1,188 @@
+package com.pythonnative.runtime.screens
+
+import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import androidx.activity.OnBackPressedCallback
+import androidx.core.os.bundleOf
+import androidx.core.view.ViewCompat
+import androidx.fragment.app.Fragment
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.PNLog
+import org.json.JSONObject
+
+/**
+ * The Fragment hosting one PythonNative screen.
+ *
+ * On view creation it asks Python to create the screen
+ * (`callback("host", screenId, "create", {...})`) and afterwards
+ * forwards lifecycle and layout: `start`, `layout`, `resume`, `pause`,
+ * `stop`, `destroy`, `back_pressed`, `save_state`, and
+ * `restore_state`. Python attaches the screen's root view through the
+ * `Host.attach_root` module call, which lands in [attachRoot].
+ *
+ * Apps subclass this (the nav graph names the subclass) and override
+ * [defaultPath] to supply the entry module when the fragment arguments
+ * don't carry one. Fast Refresh needs nothing from the fragment: the
+ * Python dev client reloads modules and refreshes mounted screens.
+ */
+open class PNScreenFragment : Fragment() {
+    /** The screen id assigned by [ScreenRegistry]. */
+    var screenId: Int = 0
+        private set
+
+    /** The container the root view is attached into (valid between `onCreateView` and `onDestroyView`). */
+    var container: FrameLayout? = null
+        private set
+
+    private var created = false
+    private var pendingRestore: String? = null
+    private var lastLayout: String? = null
+
+    /** Screen path when the arguments carry none (apps return the entry module). */
+    protected open fun defaultPath(): String? = null
+
+    /** The path this fragment shows. */
+    fun screenPath(): String? = arguments?.getString(ARG_PATH) ?: defaultPath()
+
+    private fun argsJson(): String? = arguments?.getString(ARG_ARGS)
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        screenId = ScreenRegistry.register(this)
+        pendingRestore = savedInstanceState?.getString(STATE_KEY)
+        requireActivity().onBackPressedDispatcher.addCallback(
+            this,
+            object : OnBackPressedCallback(true) {
+                override fun handleOnBackPressed() {
+                    if (created) host("back_pressed", "{}")
+                    else requireActivity().finish()
+
+                }
+            },
+        )
+    }
+
+    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
+        val frame = FrameLayout(requireContext())
+        frame.layoutParams = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
+        this.container = frame
+        return frame
+    }
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        super.onViewCreated(view, savedInstanceState)
+        arguments?.getString(ARG_TITLE)?.let { activity?.title = it }
+        val payload = JSONObject()
+            .put("path", screenPath() ?: JSONObject.NULL)
+            .put("args", argsJson() ?: JSONObject.NULL)
+        host("create", payload.toString())
+        created = true
+        pendingRestore?.let {
+            host("restore_state", JSONObject().put("state", it).toString())
+            pendingRestore = null
+        }
+        view.addOnLayoutChangeListener { v, _, _, _, _, _, _, _, _ -> publishLayout(v) }
+        ViewCompat.setOnApplyWindowInsetsListener(view) { v, insets ->
+            publishLayout(v, force = true)
+            insets
+        }
+        publishLayout(view, force = true)
+    }
+
+    private fun publishLayout(view: View, force: Boolean = false) {
+        if (!created) return
+        val payload = Viewport.describe(view).toString()
+        if (!force && payload == lastLayout) return
+        lastLayout = payload
+        host("layout", payload)
+    }
+
+    /** Current viewport payload for this screen. */
+    fun viewport(): JSONObject {
+        val v = container ?: view
+        return if (v != null) Viewport.describe(v) else JSONObject()
+    }
+
+    /** Attach `root` (MATCH_PARENT) into the fragment container, replacing any previous root. */
+    fun attachRoot(root: View) {
+        val target = container ?: return
+        target.removeAllViews()
+        (root.parent as? ViewGroup)?.removeView(root)
+        target.addView(root, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
+        publishLayout(target, force = true)
+    }
+
+    /** Detach `root` from wherever it is parented (never clears the shared container). */
+    fun detachRoot(root: View) {
+        (root.parent as? ViewGroup)?.removeView(root)
+    }
+
+    override fun onStart() {
+        super.onStart()
+        host("start", "{}")
+    }
+
+    override fun onResume() {
+        super.onResume()
+        ScreenRegistry.setActive(screenId)
+        host("resume", viewport().toString())
+    }
+
+    override fun onPause() {
+        super.onPause()
+        host("pause", "{}")
+    }
+
+    override fun onStop() {
+        super.onStop()
+        host("stop", "{}")
+    }
+
+    var cachedStateJSON: String? = null
+
+    override fun onSaveInstanceState(outState: Bundle) {
+        super.onSaveInstanceState(outState)
+        if (!created) return
+        host("save_state", "{}")
+        cachedStateJSON?.let { outState.putString(STATE_KEY, it) }
+    }
+
+    override fun onDestroyView() {
+        super.onDestroyView()
+        container = null
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        if (created) host("destroy", "{}")
+        created = false
+        ScreenRegistry.unregister(screenId)
+    }
+
+    private fun host(name: String, payloadJson: String): String? {
+        return try {
+            PNBridge.callPython("host", screenId.toLong(), name, payloadJson)
+        } catch (e: Exception) {
+            PNLog.rateLimited("host:$name", "host callback '$name' failed", e)
+            null
+        }
+    }
+
+    companion object {
+        const val ARG_PATH = "screen_path"
+        const val ARG_ARGS = "args_json"
+        const val ARG_TITLE = "title"
+        private const val STATE_KEY = "pn_screen_state"
+
+        /** Build a fragment for `path` with optional JSON `args`. */
+        @JvmStatic
+        fun newInstance(path: String, argsJson: String?): PNScreenFragment {
+            val f = PNScreenFragment()
+            f.arguments = bundleOf(ARG_PATH to path, ARG_ARGS to argsJson)
+            return f
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/screens/ScreenRegistry.kt

@@ -0,0 +1,80 @@
+package com.pythonnative.runtime.screens
+
+import android.content.res.Configuration
+import android.view.View
+import android.view.ViewGroup
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
+import com.pythonnative.runtime.PNBridge
+import org.json.JSONObject
+import kotlin.math.max
+
+/**
+ * Integer ids for live [PNScreenFragment]s. Python addresses screens
+ * by these ids in `Host` module calls and receives them as the `tag`
+ * of `host` callbacks.
+ */
+object ScreenRegistry {
+    private val screens = LinkedHashMap<Int, PNScreenFragment>()
+    private var nextId = 1
+    private var activeId = 0
+
+    /** Assign an id to `fragment`. */
+    fun register(fragment: PNScreenFragment): Int {
+        val id = nextId++
+        screens[id] = fragment
+        return id
+    }
+
+    fun unregister(id: Int) {
+        screens.remove(id)
+        if (activeId == id) activeId = screens.keys.lastOrNull() ?: 0
+    }
+
+    fun get(id: Int): PNScreenFragment? = screens[id]
+
+    /** Mark `id` as the screen the user currently sees (called on resume). */
+    fun setActive(id: Int) {
+        activeId = id
+    }
+
+    /** The visible screen's id, or `0`. */
+    fun activeId(): Int = activeId
+
+    /** The fragment container of the visible screen (overlay host for `Portal`). */
+    fun activeContainer(): ViewGroup? = screens[activeId]?.container ?: screens.values.lastOrNull()?.container
+}
+
+/** Builds the viewport payload shared by `layout`, `resume`, and `Host.viewport`. */
+object Viewport {
+    /**
+     * `{width, height, insets{top,left,bottom,right}, color_scheme, keyboard_height}`
+     * in dp, measured from `view` (falling back to display metrics when
+     * the view has not been laid out yet).
+     */
+    fun describe(view: View): JSONObject {
+        val density = PNBridge.density()
+        val metrics = view.resources.displayMetrics
+        val w = if (view.width > 0) view.width else metrics.widthPixels
+        val h = if (view.height > 0) view.height else metrics.heightPixels
+        val insets = ViewCompat.getRootWindowInsets(view)
+        val bars = insets?.getInsets(WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout())
+        val ime = insets?.getInsets(WindowInsetsCompat.Type.ime())
+        val bottomBar = bars?.bottom ?: 0
+        val keyboard = max(0, (ime?.bottom ?: 0) - bottomBar) / density
+        val night = view.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+        return JSONObject()
+            .put("width", w / density.toDouble())
+            .put("height", h / density.toDouble())
+            .put(
+                "insets",
+                JSONObject()
+                    .put("top", (bars?.top ?: 0) / density.toDouble())
+                    .put("left", (bars?.left ?: 0) / density.toDouble())
+                    .put("bottom", bottomBar / density.toDouble())
+                    .put("right", (bars?.right ?: 0) / density.toDouble()),
+            )
+            .put("color_scheme", if (night == Configuration.UI_MODE_NIGHT_YES) "dark" else "light")
+            .put("keyboard_height", keyboard.toDouble())
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/views/PNAccessibilityDelegate.kt

@@ -0,0 +1,48 @@
+package com.pythonnative.runtime.views
+
+import android.os.Build
+import android.view.View
+import android.view.accessibility.AccessibilityNodeInfo
+import androidx.core.view.accessibility.AccessibilityNodeInfoCompat
+
+/**
+ * Accessibility delegate that exposes PythonNative's `test_id` and
+ * `accessibility_state` props through the Android accessibility tree.
+ *
+ * `test_id` is surfaced as the node's view-id resource name, which
+ * UI Automator-based tools (Maestro, UiAutomator2, Appium) match as
+ * `resource-id`. State flags map onto the closest
+ * [AccessibilityNodeInfo] equivalents so TalkBack announces them.
+ * Fields left null are not applied.
+ */
+class PNAccessibilityDelegate : View.AccessibilityDelegate() {
+    var testId: String? = null
+    var stateDisabled: Boolean? = null
+    var stateSelected: Boolean? = null
+    var stateChecked: Boolean? = null
+    var stateBusy: Boolean? = null
+    var stateExpanded: Boolean? = null
+    var role: String? = null
+
+    override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {
+        super.onInitializeAccessibilityNodeInfo(host, info)
+        testId?.let { info.viewIdResourceName = it }
+        stateDisabled?.let { info.isEnabled = !it }
+        stateSelected?.let { info.isSelected = it }
+        stateChecked?.let {
+            info.isCheckable = true
+            info.isChecked = it
+        }
+        role?.let { AccessibilityNodeInfoCompat.wrap(info).roleDescription = it }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            val states = mutableListOf<String>()
+            if (stateBusy == true) states.add("busy")
+            when (stateExpanded) {
+                true -> states.add("expanded")
+                false -> states.add("collapsed")
+                null -> {}
+            }
+            if (states.isNotEmpty()) info.stateDescription = states.joinToString(", ")
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/views/PNBorderDrawable.kt

@@ -0,0 +1,76 @@
+package com.pythonnative.runtime.views
+
+import android.graphics.Canvas
+import android.graphics.ColorFilter
+import android.graphics.Paint
+import android.graphics.PixelFormat
+import android.graphics.RectF
+import android.graphics.drawable.Drawable
+
+/**
+ * Background drawable that renders an optional rounded fill plus four
+ * independent border strips. Used for PythonNative's
+ * `border_<side>_width` / `border_<side>_color` style props, which
+ * `GradientDrawable`'s single uniform stroke cannot express.
+ *
+ * Widths are in pixels; sides are ordered left, top, right, bottom.
+ * The fill color is mutable so animated `background_color` frames can
+ * update it in place without allocating a new drawable.
+ */
+class PNBorderDrawable(
+    private var hasBackground: Boolean,
+    private var backgroundColor: Int,
+    private val cornerRadius: Float,
+    private val widths: FloatArray,
+    private val colors: IntArray,
+) : Drawable() {
+    private val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+
+    /** Replace the fill color (used by animated background frames). */
+    fun setFillColor(color: Int) {
+        hasBackground = true
+        backgroundColor = color
+        invalidateSelf()
+    }
+
+    override fun draw(canvas: Canvas) {
+        val b = RectF(bounds)
+        if (hasBackground) {
+            paint.style = Paint.Style.FILL
+            paint.color = backgroundColor
+            if (cornerRadius > 0f) {
+                canvas.drawRoundRect(b, cornerRadius, cornerRadius, paint)
+            } else {
+                canvas.drawRect(b, paint)
+            }
+        }
+        paint.style = Paint.Style.FILL
+        if (widths[0] > 0f) {
+            paint.color = colors[0]
+            canvas.drawRect(b.left, b.top, b.left + widths[0], b.bottom, paint)
+        }
+        if (widths[1] > 0f) {
+            paint.color = colors[1]
+            canvas.drawRect(b.left, b.top, b.right, b.top + widths[1], paint)
+        }
+        if (widths[2] > 0f) {
+            paint.color = colors[2]
+            canvas.drawRect(b.right - widths[2], b.top, b.right, b.bottom, paint)
+        }
+        if (widths[3] > 0f) {
+            paint.color = colors[3]
+            canvas.drawRect(b.left, b.bottom - widths[3], b.right, b.bottom, paint)
+        }
+    }
+
+    override fun setAlpha(alpha: Int) {
+        paint.alpha = alpha
+    }
+
+    override fun setColorFilter(colorFilter: ColorFilter?) {
+        paint.colorFilter = colorFilter
+    }
+
+    @Deprecated("Deprecated in Java")
+    override fun getOpacity(): Int = PixelFormat.TRANSLUCENT
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/views/PNEditText.kt

@@ -0,0 +1,18 @@
+package com.pythonnative.runtime.views
+
+import android.content.Context
+import androidx.appcompat.widget.AppCompatEditText
+
+/**
+ * `EditText` that reports selection changes, which the platform only
+ * exposes through a protected override.
+ */
+class PNEditText(context: Context) : AppCompatEditText(context) {
+    /** Called with `(start, end)` whenever the selection or cursor moves. */
+    var onSelectionChangedListener: ((Int, Int) -> Unit)? = null
+
+    override fun onSelectionChanged(selStart: Int, selEnd: Int) {
+        super.onSelectionChanged(selStart, selEnd)
+        onSelectionChangedListener?.invoke(selStart, selEnd)
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/views/PNFrameLayout.kt

@@ -0,0 +1,49 @@
+package com.pythonnative.runtime.views
+
+import android.content.Context
+import android.view.MotionEvent
+import android.widget.FrameLayout
+
+/**
+ * Container `FrameLayout` with React Native-style `pointer_events`
+ * semantics. Component managers create these for flex containers and
+ * drive the mode via [setPointerEventsMode]:
+ *
+ * - `"auto"` (default): normal dispatch; the view and its children
+ *   both receive touches.
+ * - `"none"`: neither the view nor its children receive touches; the
+ *   event falls through to whatever sits underneath.
+ * - `"box_none"`: children receive touches, but the view itself never
+ *   intercepts or consumes them (the styler also mutes the view's own
+ *   touch listeners).
+ * - `"box_only"`: the view receives touches and its children don't;
+ *   every event in the subtree is intercepted at this level.
+ */
+open class PNFrameLayout(context: Context) : FrameLayout(context) {
+    private var pointerEventsMode: String = "auto"
+
+    /** Set the pointer-events mode; `null` restores `"auto"`. */
+    fun setPointerEventsMode(mode: String?) {
+        pointerEventsMode = mode ?: "auto"
+    }
+
+    /** The current pointer-events mode. */
+    fun getPointerEventsMode(): String = pointerEventsMode
+
+    override fun dispatchTouchEvent(ev: MotionEvent): Boolean {
+        if (pointerEventsMode == "none") {
+            // Declining the whole dispatch lets the event pass through
+            // to views underneath, matching RN's "none".
+            return false
+        }
+        return super.dispatchTouchEvent(ev)
+    }
+
+    override fun onInterceptTouchEvent(ev: MotionEvent): Boolean {
+        return when (pointerEventsMode) {
+            "box_only" -> true
+            "box_none" -> false
+            else -> super.onInterceptTouchEvent(ev)
+        }
+    }
+}

pythonnative/native/android/src/test/java/com/pythonnative/runtime/AnimationSpecsTest.kt

@@ -0,0 +1,75 @@
+package com.pythonnative.runtime
+
+import com.pythonnative.runtime.animation.AnimationSpecs
+import org.json.JSONArray
+import org.json.JSONObject
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import kotlin.math.exp
+import kotlin.math.sqrt
+
+class AnimationSpecsTest {
+    @Test
+    fun springDampingRatio() {
+        // Critically damped when damping = 2 * sqrt(k * m).
+        val k = 100.0
+        val m = 2.0
+        val critical = 2 * sqrt(k * m)
+        assertEquals(1.0, AnimationSpecs.dampingRatio(k, critical, m), 1e-9)
+        val spec = JSONObject("""{"kind":"spring","from":0,"to":1,"stiffness":100,"damping":10,"mass":1}""")
+        val spring = AnimationSpecs.spring(spec)
+        assertEquals(100.0, spring.stiffness, 1e-9)
+        assertEquals(0.5, spring.dampingRatio, 1e-9)
+        // Mass scales the effective stiffness so the natural frequency matches.
+        val heavy = AnimationSpecs.spring(JSONObject("""{"kind":"spring","stiffness":100,"damping":10,"mass":4}"""))
+        assertEquals(25.0, heavy.stiffness, 1e-9)
+        assertEquals(10.0 / (2 * sqrt(400.0)), heavy.dampingRatio, 1e-9)
+    }
+
+    @Test
+    fun decayFrictionReproducesPythonDecay() {
+        val k = 0.002
+        val friction = AnimationSpecs.decayFriction(k)
+        // FlingAnimation: v(t) = v0 * exp(-4.2 * friction * t); Python: v0 * exp(-k * 1000 * t).
+        val t = 0.25
+        assertEquals(exp(-k * 1000 * t), exp(-AnimationSpecs.FLING_FRICTION_SCALE * friction * t), 1e-9)
+        val decay = AnimationSpecs.decay(JSONObject("""{"kind":"decay","from":10,"velocity":2,"deceleration":0.002}"""))
+        assertEquals(2000.0, decay.startVelocity, 1e-9)
+        assertEquals(10.0 + 2.0 / (0.002 * 1000.0), decay.projectedFinal, 1e-9)
+    }
+
+    @Test
+    fun timingDefaults() {
+        val timing = AnimationSpecs.timing(JSONObject("""{"kind":"timing","from":0,"to":1}"""))
+        assertEquals(300L, timing.durationMs)
+        assertEquals(1.0, timing.to, 0.0)
+    }
+
+    @Test
+    fun easingNamesMatchPythonCurves() {
+        @Suppress("UNCHECKED_CAST")
+        val easeInOut = AnimationSpecs.resolveEasing("ease_in_out") as (Float) -> Float
+        assertEquals(0.5f, easeInOut(0.5f), 1e-6f)
+        assertEquals(0.15625f, easeInOut(0.25f), 1e-6f)
+        @Suppress("UNCHECKED_CAST")
+        val linear = AnimationSpecs.resolveEasing("linear") as (Float) -> Float
+        assertEquals(0.3f, linear(0.3f), 1e-6f)
+        @Suppress("UNCHECKED_CAST")
+        val fallback = AnimationSpecs.resolveEasing("does-not-exist") as (Float) -> Float
+        assertEquals(easeInOut(0.3f), fallback(0.3f), 1e-6f)
+        @Suppress("UNCHECKED_CAST")
+        val bounce = AnimationSpecs.resolveEasing("bounce") as (Float) -> Float
+        assertEquals(1f, bounce(1f), 1e-6f)
+        assertTrue(bounce(0.5f) in 0f..1f)
+    }
+
+    @Test
+    fun cubicBezierArraysAreControlPoints() {
+        val pts = AnimationSpecs.resolveEasing(JSONArray("[0.25, 0.1, 0.25, 1.0]")) as DoubleArray
+        assertArrayEquals(doubleArrayOf(0.25, 0.1, 0.25, 1.0), pts, 1e-9)
+        val css = AnimationSpecs.resolveEasing("cubic-bezier(0.42, 0, 1, 1)") as DoubleArray
+        assertArrayEquals(doubleArrayOf(0.42, 0.0, 1.0, 1.0), css, 1e-9)
+    }
+}