ActionUIAppKitApplication: add alert API

actionUIAppRunAlert() allows clients to present a modal dialog with configurable title, message, alert style and buttons

Author: abra-code

ActionUIAppKitApplication/ActionUIApp.swift

@@ -433,6 +433,66 @@ private func actionStrdup(_ string: String) -> UnsafeMutablePointer<CChar> {
     return string.withCString { strdup($0)! }
 }
 
+// MARK: - Alert dialog
+
+/// Run a modal alert dialog and return the title of the button that was clicked.
+///
+/// Config JSON keys (all optional):
+///   title: String              — bold heading text
+///   message: String            — informative text below the title
+///   style: String              — "informational" (default), "warning", or "critical"
+///   buttons: [String]          — button titles, first is the default (rightmost),
+///                                 second is placed to its left, etc.
+///                                 Defaults to ["OK"] if omitted.
+///
+/// Returns the title of the clicked button as a C string, or nil on error.
+@_cdecl("actionUIAppRunAlert")
+public func actionUIAppRunAlert(
+    _ configJSON: UnsafePointer<CChar>?
+) -> UnsafeMutablePointer<CChar>? {
+    let jsonString = configJSON.map { String(cString: $0) }
+    return runOnMainActorSync {
+        var config: [String: Any] = [:]
+        if let json = jsonString,
+           let data = json.data(using: .utf8),
+           let parsed = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+            config = parsed
+        }
+
+        let alert = NSAlert()
+
+        if let title = config["title"] as? String {
+            alert.messageText = title
+        }
+        if let message = config["message"] as? String {
+            alert.informativeText = message
+        }
+
+        switch config["style"] as? String {
+        case "warning":
+            alert.alertStyle = .warning
+        case "critical":
+            alert.alertStyle = .critical
+        default:
+            alert.alertStyle = .informational
+        }
+
+        let buttons = config["buttons"] as? [String] ?? ["OK"]
+        for title in buttons {
+            alert.addButton(withTitle: title)
+        }
+
+        let response = alert.runModal()
+
+        // NSAlert buttons are numbered .alertFirstButtonReturn, +1, +2, …
+        let index = response.rawValue - NSApplication.ModalResponse.alertFirstButtonReturn.rawValue
+        if index >= 0 && index < buttons.count {
+            return actionStrdup(buttons[index])
+        }
+        return nil
+    }
+}
+
 // MARK: - File panels (NSOpenPanel / NSSavePanel)
 
 /// Parse a JSON config dictionary and configure an `NSOpenPanel`.

ActionUIPython/actionui.py

@@ -469,6 +469,51 @@ def _build_panel_config(**kwargs) -> Dict[str, Any]:
             config["allowsOtherFileTypes"] = True
         return config
 
+    # ------------------------------------------------------------------
+    # Alert dialog
+    # ------------------------------------------------------------------
+
+    def alert(self, *,
+              title: Optional[str] = None,
+              message: Optional[str] = None,
+              style: str = "informational",
+              buttons: Optional[List[str]] = None) -> Optional[str]:
+        """Run a modal alert dialog.
+
+        Args:
+            title:    Bold heading text.
+            message:  Informative text below the title.
+            style:    ``"informational"`` (default), ``"warning"``, or
+                      ``"critical"``.
+            buttons:  List of button titles. The first is the default
+                      (rightmost) button.  Defaults to ``["OK"]``.
+
+        Returns:
+            The title of the clicked button, or ``None`` on error.
+
+        Example::
+
+            result = app.alert(
+                title="Replace Pipeline?",
+                message="The current pipeline is not empty.",
+                style="warning",
+                buttons=["Replace", "Cancel"],
+            )
+            if result == "Replace":
+                ...
+        """
+        config: Dict[str, Any] = {}
+        if title is not None:
+            config["title"] = title
+        if message is not None:
+            config["message"] = message
+        if style != "informational":
+            config["style"] = style
+        if buttons is not None:
+            config["buttons"] = buttons
+        config_json = json.dumps(config) if config else None
+        return _actionui.app_run_alert(config_json)
+
     # ------------------------------------------------------------------
     # Menu bar
     # ------------------------------------------------------------------

ActionUIPython/actionui_native.m

@@ -352,6 +352,16 @@ static void app_window_will_present_bridge(const char* windowUUID) {
     return py_result;
 }
 
+static PyObject* py_app_run_alert(PyObject* self, PyObject* args) {
+    const char* configJSON = NULL;
+    if (PyArg_ParseTuple(args, "|z", &configJSON) == 0) return NULL;
+    char* result = actionUIAppRunAlert(configJSON);
+    if (result == NULL) Py_RETURN_NONE;
+    PyObject* py_result = PyUnicode_FromString(result);
+    actionUIFreeString(result);
+    return py_result;
+}
+
 // MARK: - Python API: Version
 
 static PyObject* py_get_version(PyObject* self, PyObject* args) {
@@ -879,6 +889,8 @@ static void app_window_will_present_bridge(const char* windowUUID) {
      "app_run_open_panel([configJSON]) -> str|None — run NSOpenPanel; returns JSON array of paths or None."},
     {"app_run_save_panel",            py_app_run_save_panel,            METH_VARARGS,
      "app_run_save_panel([configJSON]) -> str|None — run NSSavePanel; returns path or None."},
+    {"app_run_alert",                 py_app_run_alert,                 METH_VARARGS,
+     "app_run_alert([configJSON]) -> str|None — run modal NSAlert; returns clicked button title or None."},
 
     {NULL, NULL, 0, NULL}
 };