---@meta
---@diagnostic disable: missing-return
-- Type stubs for the native `tui` module: interactive prompts, styled output,
-- message blocks and terminal control. Always available as the global `tui`.
-- Reference: docs/tui.md
--
-- Shared prompt behavior: Esc returns nil; Ctrl-C raises "<fn>: interrupted";
-- prompting without a terminal raises "<fn>: not a terminal". Prompts are
-- async — they suspend only the calling coroutine.

tui = {}

----------------------------------------------------------------------
-- Prompts
----------------------------------------------------------------------

---@class tui.ConfirmOpts
---@field help string? hint line shown below the prompt
---@field placeholder string? dim hint shown while the input is empty

---Yes/no question, answered with y/n. `default` is returned on plain Enter;
---with nil the user must type an answer. Esc returns nil (distinct from false).
---@param text string
---@param default boolean?
---@param opts tui.ConfirmOpts?
---@return boolean? answer
function tui.confirm(text, default, opts) end

---@class tui.TextOpts
---@field help string?
---@field placeholder string? dim hint shown while the input is empty
---@field default string? returned when the input is submitted empty (distinct from the pre-filled positional default)
---@field minLen integer? length bound, enforced inline
---@field maxLen integer? length bound, enforced inline
---@field suggestions string[]? autocompletion candidates (substring filter, Tab completes)
---@field pageSize integer? visible suggestion rows

---One-line text input. The positional `default` is pre-filled, editable text.
---@param text string
---@param default string?
---@param opts tui.TextOpts?
---@return string? answer
function tui.promptText(text, default, opts) end

---@class tui.LongTextOpts
---@field help string?
---@field extension string? temp-file extension for editor syntax highlighting (default ".txt")
---@field editor string? editor command instead of $VISUAL/$EDITOR

---Multi-line input via an external editor ($VISUAL/$EDITOR) on a temp file.
---@param text string
---@param default string? text the editor buffer starts with
---@param opts tui.LongTextOpts?
---@return string? answer
function tui.promptLongText(text, default, opts) end

---@class tui.SelectOpts
---@field options string[] the choices (required, non-empty)
---@field help string?
---@field multiple boolean? checkbox multi-select; result becomes string[]
---@field pageSize integer? visible rows (default 7)
---@field vimMode boolean? hjkl navigation
---@field filter boolean? set false to disable type-to-filter
---@field minSelected integer? multiple only, enforced inline
---@field maxSelected integer? multiple only, enforced inline
---@field allSelected boolean? multiple only: start with everything checked

---Pick from a list (filterable). `default` is matched against the options by
---value; a value not among them raises. With `opts.multiple` the default may
---be a string or array of strings and the result is an array.
---@param text string
---@param default string|string[]|nil
---@param opts tui.SelectOpts
---@return string|string[]|nil answer
function tui.promptSelect(text, default, opts) end

---@class tui.SecretOpts
---@field help string?
---@field confirm boolean? ask twice and require both entries to match
---@field display "masked"|"hidden"|"full"? echo mode (default "masked")
---@field toggle boolean? allow Ctrl-R to reveal the input
---@field minLen integer? enforced inline

---Secret input. Deliberately has no default parameter.
---@param text string
---@param opts tui.SecretOpts?
---@return string? answer
function tui.promptSecret(text, opts) end

---@class tui.NumberOpts
---@field help string?
---@field placeholder string?
---@field min number? enforced inline
---@field max number? enforced inline

---Numeric input, re-prompted until it parses. `default` is returned on empty submit.
---@param text string
---@param default number?
---@param opts tui.NumberOpts?
---@return number? answer
function tui.promptNumber(text, default, opts) end

---Whole-number input, re-prompted until it parses. A fractional `default`
---raises at call time.
---@param text string
---@param default integer?
---@param opts tui.NumberOpts?
---@return integer? answer
function tui.promptInt(text, default, opts) end

---@class tui.DateOpts
---@field help string?
---@field min string? earliest selectable date, "YYYY-MM-DD"
---@field max string? latest selectable date, "YYYY-MM-DD"
---@field weekStart string? first day of the week, e.g. "monday" (default Sunday)

---Interactive calendar. Dates cross the API as "YYYY-MM-DD" strings.
---@param text string
---@param default string? initially selected date, "YYYY-MM-DD"
---@param opts tui.DateOpts?
---@return string? date
function tui.promptDate(text, default, opts) end

----------------------------------------------------------------------
-- Styled output
----------------------------------------------------------------------

---Render HTML-like style tags (`<info>`, `<fg=#c0392b;options=bold>`, shorthand
---`<red;on-white;b>`, `<href=URL>`, action tags like `<clear=line>`) into a
---string with ANSI escapes. Degrades to plain text when piped or NO_COLOR is
---set. `</>` closes the innermost style; invalid tags pass through literally.
---@param markup string
---@return string
function tui.styled(markup) end

---Backslash-escape the markup metacharacters (`<`, `>`, `\`) so untrusted
---text — user input, API data — can be embedded in a `tui.styled` format
---string and come out verbatim, without breaking the surrounding markup.
---@param text string
---@return string
function tui.escape(text) end

---Register a custom tag for `tui.styled` and block styles. The spec uses tag
---syntax: attributes ("fg=white;bg=magenta"), shorthand ("i;bold"), or another
---preset name. Re-registering overwrites; presets may shadow built-ins.
---@param name string identifier-like tag name
---@param style string
function tui.addPreset(name, style) end

----------------------------------------------------------------------
-- Message blocks (print directly to stdout, plain-text message)
----------------------------------------------------------------------

---@class tui.BlockOpts
---@field label string? the "[LABEL]" text
---@field style string? tag-body syntax: preset name, spec or shorthand
---@field prefix string? prepended to every line (default " ")
---@field padding boolean? blank styled line above and below

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.success(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.error(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.warning(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.caution(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.info(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.note(message, opts) end

---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.comment(message, opts) end

---Generic block: everything comes from opts.
---@param message string|string[]
---@param opts tui.BlockOpts?
function tui.block(message, opts) end

---@class tui.OutlineOpts
---@field title string? shown in the top border
---@field style string? border color, tag-body syntax
---@field padding boolean? blank line above/below the content inside the box (default true)

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineSuccess(message, opts) end

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineError(message, opts) end

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineWarning(message, opts) end

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineNote(message, opts) end

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineInfo(message, opts) end

---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineCaution(message, opts) end

---Generic outline block.
---@param message string|string[]
---@param opts tui.OutlineOpts?
function tui.outlineBlock(message, opts) end

----------------------------------------------------------------------
-- Low-level output
----------------------------------------------------------------------

---Write arguments to stdout with no newline and no separator (each converted
---with tostring), then flush.
---@param ... any
function tui.raw(...) end

---@class tui.ScreenInfo
---@field width integer? terminal width in cells; nil when there is no terminal
---@field height integer? terminal height in cells; nil when there is no terminal
---@field tty boolean whether stdout is a terminal
---@field colors boolean whether styled output will actually emit colors

---Facts about the terminal, for scripts that render their own UI.
---@return tui.ScreenInfo
function tui.screenInfo() end

----------------------------------------------------------------------
-- Terminal control (no-ops without a terminal; bad arguments always raise;
-- alternate screen / cursor / scroll region / title restored on exit)
----------------------------------------------------------------------

---Absolute cursor move, 1-based. nil for one axis keeps it.
---@param row integer?
---@param col integer?
function tui.moveTo(row, col) end

---Relative cursor move: positive dx right, positive dy down; nil counts as 0.
---@param dx integer?
---@param dy integer?
function tui.move(dx, dy) end

---Save the cursor position (one slot).
function tui.saveCursor() end

---Restore the saved cursor position.
function tui.restoreCursor() end

---Ask the terminal where the cursor is (1-based). Returns nil when there is
---no terminal or it does not answer. Async, serialized against prompts.
---@return integer? row
---@return integer? col
function tui.cursorPos() end

---Hide (false) or show (true or no argument) the cursor.
---@param visible boolean?
function tui.showCursor(visible) end

---@class tui.CursorStyleOpts
---@field blink boolean?

---Set the cursor shape; no arguments reset to the terminal default.
---@param style "block"|"underline"|"bar"|nil
---@param opts tui.CursorStyleOpts?
function tui.cursorStyle(style, opts) end

---Erase the current line. mode: 0/nil = whole (cursor to column 1),
----1 = up to the cursor, 1 = cursor to end (cursor stays).
---@param mode integer?
function tui.clearLine(mode) end

---Erase the screen. mode: 0/nil = whole (cursor home), -1 = above the cursor,
---1 = below the cursor (cursor stays).
---@param mode integer?
function tui.clearScreen(mode) end

---Switch to (true) or back from (false) the alternate screen buffer.
---@param on boolean
function tui.altScreen(on) end

---Restrict scrolling to rows top..bottom (1-based, inclusive); moves the
---cursor home. No arguments reset to the full screen.
---@param top integer?
---@param bottom integer?
function tui.scrollRegion(top, bottom) end

---Scroll the scroll region: positive n up, negative down. Cursor stays.
---@param n integer
function tui.scroll(n) end

---Set the terminal window title (restored on exit). Control characters raise.
---@param text string
function tui.setTitle(text) end

---Copy text into the system clipboard via the terminal (OSC 52). Write-only.
---@param text string
function tui.setClipboard(text) end

---Soft-reset the terminal (DECSTR) without clearing the screen.
function tui.reset() end