You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
318 lines
11 KiB
318 lines
11 KiB
---@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
|
|
|