feat(ui): add native WheelPicker primitive (#8307)

* feat(ui): add native WheelPicker primitive (#5873)

* chore(ui): pin WheelPicker's callback tables in the GC frontier ratchet

The two new thread-local tables in the iOS and visionOS wheel_picker park a
NaN-boxed on_change closure that no registered scanner reaches — the same
shape as the 112 UI callback tables already pinned. Pin them deliberately so
lint reflects the debt instead of hiding it, and add the changelog fragment.

---------

Co-authored-by: Ralph Kuepper <ralph@skelpo.com>

Author: proggeramlug

android-build/app/src/main/java/com/perry/app/PerryBridge.kt

@@ -350,6 +350,15 @@ object PerryBridge {
         seekBar.progress = progress
     }
 
+    // --- NumberPicker (WheelPicker) callback ---
+
+    @JvmStatic
+    fun setNumberPickerCallback(picker: NumberPicker, callbackKey: Long) {
+        picker.setOnValueChangedListener { _, _, newValue ->
+            nativeInvokeCallback1(callbackKey, newValue.toDouble())
+        }
+    }
+
     // --- Context menu ---
 
     @JvmStatic

changelog.d/8307-ui-wheel-picker.md

@@ -0,0 +1,23 @@
+### Added
+
+- **`WheelPicker` — a native scrolling wheel/drum selector (#5873).** Renders a
+  real platform wheel where one exists (`UIPickerView` on iOS/tvOS/visionOS,
+  `NumberPicker` on Android) and a scroll-capable native control elsewhere
+  (macOS, Windows, GTK4, watchOS), so the widget is available on every target
+  rather than only the ones with a first-class drum control.
+
+  Dispatch is wired across all four backends — native, JS (`web_runtime.js`),
+  WASM (`ui_method_map.rs`), and ArkTS — plus the shared UI dispatch table, HIR
+  lowering, the API manifest, `perry.d.ts`, and the widget docs, so the same
+  TypeScript source compiles on each.
+
+  Each platform's implementation parks its per-handle `on_change` closure in a
+  thread-local `CALLBACKS` table, matching the existing `COMBOBOX_CALLBACKS`
+  pattern that every other callback-bearing widget uses. Those tables are
+  NaN-boxed-callback holders that no registered GC scanner reaches, so the two
+  new ones (iOS, visionOS) are pinned in the `frontier` ratchet of
+  `scripts/gc_runtime_root_holders.json` alongside the other 112 UI callback
+  tables — deliberately, not silently: registering per-crate scanners over the
+  whole `perry-ui*` tier remains the real fix and the ratchet may only shrink.
+  The sibling `SELECTED` tables are pinned for the same shape reason but hold
+  only row indices, never a heap value.

crates/perry-api-manifest/src/entries/part_4.rs

@@ -348,6 +348,10 @@ pub(crate) const API_MANIFEST_PART_4: &[ApiEntry] = &[
     method("perry/ui", "Slider", false, None),
     method("perry/ui", "ProgressView", false, None),
     method("perry/ui", "Picker", false, None),
+    method("perry/ui", "WheelPicker", false, None),
+    method("perry/ui", "wheelPickerAddItem", false, None),
+    method("perry/ui", "wheelPickerGetSelected", false, None),
+    method("perry/ui", "wheelPickerSetSelected", false, None),
     method("perry/ui", "ImageFile", false, None),
     method("perry/ui", "ImageSymbol", false, None),
     method("perry/ui", "loadImage", false, None),

crates/perry-codegen-arkts/src/emit_widget.rs

@@ -142,6 +142,7 @@ pub(crate) fn emit_widget(
                     mutations,
                 ),
                 "Picker" => emit_picker(args, callbacks),
+                "WheelPicker" => emit_wheel_picker(args, callbacks),
                 // Issue #475 — Combobox(initial, onChange) maps to ArkUI
                 // Select. Runtime-added items (`comboboxAddItem`) are
                 // currently not folded into the static options array;

crates/perry-codegen-arkts/src/tests/containers.rs

@@ -579,6 +579,21 @@ fn picker_with_options_and_closure() {
     assert_eq!(r.callbacks.len(), 1);
 }
 
+#[test]
+fn wheel_picker_uses_native_looping_text_picker() {
+    let mut m = empty_module();
+    m.init
+        .push(app_with_body(nmc("WheelPicker", vec![closure_stub()])));
+    let r = emit_index_ets(&mut m).unwrap().unwrap();
+    assert!(r
+        .ets_source
+        .contains("TextPicker({ range: [], value: '' }).canLoop(true)"));
+    assert!(r
+        .ets_source
+        .contains("perryEntry.invokeCallback1(0, index)"));
+    assert_eq!(r.callbacks.len(), 1);
+}
+
 #[test]
 fn combobox_emits_arkui_select() {
     // Issue #475 — Combobox(initial, onChange) → Select with onSelect.

crates/perry-codegen-arkts/src/util.rs

@@ -209,6 +209,7 @@ pub(crate) fn is_widget_factory(name: &str) -> bool {
             | "Toggle"
             | "Slider"
             | "Picker"
+            | "WheelPicker"
             | "Combobox"
             | "RichTextEditor"
             | "Calendar"

crates/perry-codegen-arkts/src/widgets/inputs.rs

@@ -195,6 +195,27 @@ pub(crate) fn emit_picker(args: &[Expr], callbacks: &mut Vec<Expr>) -> String {
     )
 }
 
+/// `WheelPicker(onChange)` -> ArkUI's native looping `TextPicker`.
+pub(crate) fn emit_wheel_picker(args: &[Expr], callbacks: &mut Vec<Expr>) -> String {
+    let onchange = match args.first() {
+        Some(closure @ Expr::Closure { .. }) => {
+            let idx = callbacks.len();
+            callbacks.push(closure.clone());
+            format!(
+                ".onChange((_value: string, index: number) => {{\n    \
+                 perryEntry.invokeCallback1({}, index);\n    \
+                 {drain}\
+                 }})",
+                idx,
+                drain = drain_loop_body()
+            )
+        }
+        _ => String::new(),
+    };
+
+    format!("TextPicker({{ range: [], value: '' }}).canLoop(true){onchange}")
+}
+
 /// Issue #475 — `Combobox(initial, onChange)` → ArkUI `Select([...])` with
 /// `.value()` / `.selected()` / `.onSelect()`. ArkUI's Select takes a
 /// `SelectOption[]` (each option is `{value: string}`); `.value()` sets

crates/perry-codegen-js/src/emit/calls.rs

@@ -152,6 +152,10 @@ impl JsEmitter {
             "ProgressView" | "progressview_create" => "perry_ui_progressview_create",
             "Image" | "image_create" => "perry_ui_image_create",
             "Picker" | "picker_create" => "perry_ui_picker_create",
+            "WheelPicker" | "wheel_picker_create" => "perry_ui_wheel_picker_create",
+            "wheelPickerAddItem" => "perry_ui_wheel_picker_add_item",
+            "wheelPickerSetSelected" => "perry_ui_wheel_picker_set_selected",
+            "wheelPickerGetSelected" => "perry_ui_wheel_picker_get_selected",
             // Table (issue #192)
             "Table" | "table_create" => "perry_ui_table_create",
             "tableSetColumnHeader" => "perry_ui_table_set_column_header",

crates/perry-codegen-js/src/web_runtime.js

@@ -343,6 +343,20 @@ function perry_ui_picker_create(items_json, selected, callback) {
     return wrapWidget(allocHandle(el));
 }
 
+// Issue #5873: persistent wheel/list selector. This follows the native
+// one-callback ABI and receives options through wheelPickerAddItem.
+function perry_ui_wheel_picker_create(callback) {
+    const el = document.createElement("select");
+    el.size = 5;
+    el.className = "perry-wheel-picker";
+    el.style.overflowY = "auto";
+    el.style.scrollSnapType = "y mandatory";
+    if (typeof callback === "function") {
+        el.addEventListener("change", () => callback(el.selectedIndex));
+    }
+    return wrapWidget(allocHandle(el));
+}
+
 function perry_ui_form_create() {
     const el = document.createElement("form");
     el.addEventListener("submit", e => e.preventDefault());
@@ -1503,6 +1517,26 @@ function perry_ui_picker_get_selected(h) {
     return el ? el.selectedIndex : -1;
 }
 
+function perry_ui_wheel_picker_add_item(h, title) {
+    const el = getHandle(h);
+    if (!el) return;
+    const opt = document.createElement("option");
+    opt.value = el.children.length;
+    opt.textContent = title;
+    opt.style.scrollSnapAlign = "center";
+    el.appendChild(opt);
+}
+
+function perry_ui_wheel_picker_set_selected(h, index) {
+    const el = getHandle(h);
+    if (el) el.selectedIndex = index;
+}
+
+function perry_ui_wheel_picker_get_selected(h) {
+    const el = getHandle(h);
+    return el ? el.selectedIndex : -1;
+}
+
 // --- Image Operations ---
 function perry_ui_image_create_symbol(name) {
     const el = document.createElement("span");
@@ -3601,6 +3635,7 @@ window.__perry = {
     perry_ui_progressview_create,
     perry_ui_image_create,
     perry_ui_picker_create,
+    perry_ui_wheel_picker_create,
     perry_ui_form_create,
     perry_ui_section_create,
     perry_ui_navigationstack_create,
@@ -3686,6 +3721,9 @@ window.__perry = {
     perry_ui_picker_add_item,
     perry_ui_picker_set_selected,
     perry_ui_picker_get_selected,
+    perry_ui_wheel_picker_add_item,
+    perry_ui_wheel_picker_set_selected,
+    perry_ui_wheel_picker_get_selected,
     // Image
     perry_ui_image_create_symbol,
     perry_ui_image_create_url,

crates/perry-codegen-wasm/src/emit/ui_method_map.rs

@@ -22,6 +22,7 @@ pub(super) fn map_ui_method(method: &str, class_name: Option<&str>) -> &'static
         "ProgressView" | "progressview_create" => "perry_ui_progressview_create",
         "Image" | "image_create" => "perry_ui_image_create",
         "Picker" | "picker_create" => "perry_ui_picker_create",
+        "WheelPicker" | "wheel_picker_create" => "perry_ui_wheel_picker_create",
         "Form" | "form_create" => "perry_ui_form_create",
         "Section" | "section_create" => "perry_ui_section_create",
         "NavigationStack" | "navigationstack_create" => "perry_ui_navigationstack_create",
@@ -178,6 +179,9 @@ pub(super) fn map_ui_method(method: &str, class_name: Option<&str>) -> &'static
         "pickerAddItem" => "perry_ui_picker_add_item",
         "pickerSetSelected" => "perry_ui_picker_set_selected",
         "pickerGetSelected" => "perry_ui_picker_get_selected",
+        "wheelPickerAddItem" => "perry_ui_wheel_picker_add_item",
+        "wheelPickerSetSelected" => "perry_ui_wheel_picker_set_selected",
+        "wheelPickerGetSelected" => "perry_ui_wheel_picker_get_selected",
         // Camera (issue #191) — Web has no live-camera FFI yet, so the
         // wasm_runtime.js stubs return 0 / -1. The dispatch entries here
         // exist so user code calling `CameraView()` from a browser build