///|
/// # PromptX
///
/// PromptX 是一个用于 MoonBit 的命令行交互式提示库，封装了底层 C 终端
/// 交互库 cprompt。它提供了简洁的 API 来向用户收集文本、确认、单选、
/// 多选与密码等输入。
///
/// ## 功能特性
///
/// - **Input**: 单行文本输入，支持默认值占位
/// - **Confirm**: 是/否确认
/// - **Select**: 单选列表
/// - **Checkbox**: 多选列表
/// - **Password**: 密码输入（不回显）
///
/// ## 快速开始
///
/// ```mbt nocheck
/// import "wangmingfa/promptx"
///
/// fn main {
///   let name = @promptx.input("What is your name?", default_value="Guest")
///   println("Hello, \{name}!")
///
///   let ok = @promptx.confirm("Continue?")
///   if ok {
///     let color = @promptx.select("Pick a color:", ["Red", "Green", "Blue"])
///     println("You picked: \{color}")
///   }
/// }
/// ```

///|
/// 单行文本输入。
///
/// 在终端中显示一个带默认值的灰色占位提示；用户直接在提示后输入文本，
/// 按回车确认。若用户未输入任何内容直接回车，则返回 `default_value`。
///
/// ### 参数
///
/// - `message : String` - 显示给用户的问题文本
/// - `default_value~ : String` - 可选的默认值（默认空字符串）
///
/// ### 返回值
///
/// 返回用户输入的文本，或默认值。
///
/// ### 示例
///
/// ```mbt nocheck
/// let name = @promptx.input("Your name?", default_value="Guest")
/// ```
pub fn input(message : String, default_value? : String = "") -> String {
  @cprompt.prompt_input_mb(message, default_value~)
}

///|
/// 是/否确认。
///
/// 显示问题并等待用户输入。返回 `true` 表示确认，`false` 表示否定。
/// 当用户取消（Ctrl-C）时返回 `false`。
///
/// ### 参数
///
/// - `message : String` - 显示给用户的问题文本
/// - `default_value~ : Bool` - 可选的默认值（默认 `false`）
///
/// ### 返回值
///
/// `true` 表示 Yes，`false` 表示 No 或取消。
///
/// ### 示例
///
/// ```mbt nocheck
/// if @promptx.confirm("Save changes?") {
///   println("Saving...")
/// }
/// ```

///|
/// Internal helper: turn the C confirm result (`-1` cancelled, `0` no,
/// `1` yes) into a Bool. Only an explicit "yes" (`1`) is true; a cancelled
/// session (`-1`) is treated as "not confirmed" for safety.
fn confirm_to_bool(c : Int) -> Bool {
  c == 1
}

///|
pub fn confirm(message : String, default_value? : Bool = false) -> Bool {
  confirm_to_bool(@cprompt.prompt_confirm_mb(message, default_value~))
}

///|
/// 单选列表。
///
/// 显示一个可上下移动光标选择的选项列表，按回车确认。
///
/// ### 参数
///
/// - `message : String` - 显示给用户的问题文本
/// - `choices : Array[String]` - 可选项数组
/// - `default_index~ : Int` - 默认选中的索引（默认 `0`）
///
/// ### 返回值
///
/// 返回用户选中的选项字符串。
///
/// ### 示例
///
/// ```mbt nocheck
/// let color = @promptx.select("Pick a color:", ["Red", "Green", "Blue"])
/// ```
pub fn select(
  message : String,
  choices : Array[String],
  default_index? : Int = 0,
) -> String {
  @cprompt.prompt_select_mb(message, choices, default_index~)
}

///|
/// 多选列表。
///
/// 显示一个可逐项勾选（空格）的选项列表，按回车确认。
///
/// ### 参数
///
/// - `message : String` - 显示给用户的问题文本
/// - `choices : Array[String]` - 可选项数组
/// - `default_items~ : Array[String]` - 默认已勾选项（默认空）
///
/// ### 返回值
///
/// 返回以逗号分隔的选中项字符串，例如 `"A,C"`。
///
/// ### 示例
///
/// ```mbt nocheck
/// let tops = @promptx.checkbox("Toppings:", ["Cheese", "Pepperoni", "Onion"])
/// ```
pub fn checkbox(
  message : String,
  choices : Array[String],
  default_items? : Array[String] = [],
) -> String {
  @cprompt.prompt_checkbox_mb(message, choices, default_items~)
}

///|
/// 密码输入。
///
/// 显示问题并收集输入，但输入内容不会回显到终端。
///
/// ### 参数
///
/// - `message : String` - 显示给用户的问题文本
///
/// ### 返回值
///
/// 返回用户输入的密码字符串。
///
/// ### 示例
///
/// ```mbt nocheck
/// let pwd = @promptx.password("Enter password:")
/// ```
pub fn password(message : String) -> String {
  @cprompt.prompt_password_mb(message)
}