import pyratatui
print(pyratatui.__version__)          # "0.2.7"
print(pyratatui.__ratatui_version__)  # "0.30"

from pyratatui import Block, Color, Paragraph, Style, Terminal

with Terminal() as term:
    while True:
        def ui(frame):
            frame.render_widget(
                Paragraph.from_string("Hello, pyratatui! 🐀  Press q to quit.")
                    .block(Block().bordered().title("Hello World"))
                    .style(Style().fg(Color.cyan())),
                frame.area,
            )
        term.draw(ui)
        ev = term.poll_event(timeout_ms=100)
        if ev and ev.code == "q":
            break

from pyratatui import Paragraph, run_app

def ui(frame):
    frame.render_widget(
        Paragraph.from_string("Hello! Press q to quit."),
        frame.area,
    )

run_app(ui)

with Terminal() as term:
    term.draw(lambda frame: ...)    # pyratatui creates frame and passes it in
    ev = term.poll_event(timeout_ms=50)  # KeyEvent | None

def ui(frame):
    area = frame.area  # Rect — full terminal size
    frame.render_widget(widget, area)

from pyratatui import (
    Block,
    Constraint,
    Direction,
    Layout,
    Paragraph,
    run_app,
)

def ui(frame):
    header, body, footer = (
        Layout()
        .direction(Direction.Vertical)
        .constraints([
            Constraint.length(3),   # fixed 3 rows
            Constraint.fill(1),     # takes remaining space
            Constraint.length(1),   # fixed 1 row
        ])
        .split(frame.area)
    )

    frame.render_widget(Block().bordered().title("Header"), header)
    frame.render_widget(
        Paragraph.from_string("Main content").block(Block().bordered().title("Body")),
        body,
    )
    frame.render_widget(Paragraph.from_string("Press q to quit"), footer)

run_app(ui)

from pyratatui import Style, Color, Modifier

style = (
    Style()
    .fg(Color.cyan())
    .bg(Color.rgb(30, 30, 46))
    .bold()
    .italic()
)

# Named colors
Color.red()    Color.green()    Color.yellow()
Color.blue()   Color.magenta()  Color.cyan()
Color.white()  Color.gray()     Color.dark_gray()
# Light variants: Color.light_red(), Color.light_green(), ...
# 256-color: Color.indexed(42)
# True-color: Color.rgb(255, 100, 0)

from pyratatui import Block, Color, Line, Paragraph, Span, Style, Text, run_app

def ui(frame):
    text = Text([
        Line([
            Span("Status: ", Style().bold()),
            Span("OK", Style().fg(Color.green())),
            Span("  |  99.9%", Style().fg(Color.cyan())),
        ]),
        Line.from_string("Plain text line"),
        Line.from_string("Right-aligned").right_aligned(),
    ])

    frame.render_widget(
        Paragraph(text).block(Block().bordered().title("Text Hierarchy")),
        frame.area,
    )

run_app(ui)

ev = term.poll_event(timeout_ms=100)
if ev:
    print(ev.code)   # "q", "Enter", "Up", "Down", "F1", etc.
    print(ev.ctrl)   # True if Ctrl held
    print(ev.alt)    # True if Alt held
    print(ev.shift)  # True if Shift held

# Common key codes
# Letters/digits: "a", "Z", "5"
# Special:        "Enter", "Esc", "Backspace", "Tab", "BackTab"
# Arrows:         "Up", "Down", "Left", "Right"
# Function:       "F1" … "F12"
# Ctrl+C:         ev.code == "c" and ev.ctrl

from pyratatui import (
    Block,
    Color,
    Constraint,
    Direction,
    Gauge,
    Layout,
    List,
    ListItem,
    ListState,
    Row,
    Sparkline,
    Style,
    Table,
    TableState,
    Tabs,
    run_app,
)

list_state = ListState()
list_state.select(0)

table_state = TableState()
table_state.select(0)

def ui(frame, _list_state=list_state, _table_state=table_state):
    rows = (
        Layout()
        .direction(Direction.Vertical)
        .constraints([
            Constraint.length(3),
            Constraint.length(3),
            Constraint.fill(1),
            Constraint.length(5),
        ])
        .split(frame.area)
    )
    middle = (
        Layout()
        .direction(Direction.Horizontal)
        .constraints([Constraint.percentage(40), Constraint.fill(1)])
        .split(rows[2])
    )

    frame.render_widget(
        Tabs(["Overview", "Logs", "Config"])
        .select(1)
        .block(Block().bordered().title("Tabs"))
        .highlight_style(Style().fg(Color.yellow()).bold()),
        rows[0],
    )

    frame.render_widget(
        Gauge()
        .percent(75)
        .label("CPU 75%")
        .style(Style().fg(Color.green()))
        .block(Block().bordered().title("Gauge")),
        rows[1],
    )

    items = [ListItem(s) for s in ["Alpha", "Beta", "Gamma"]]
    frame.render_stateful_list(
        List(items)
        .block(Block().bordered().title("List"))
        .highlight_style(Style().fg(Color.yellow()).bold())
        .highlight_symbol("▶ "),
        middle[0],
        _list_state,
    )

    header = Row.from_strings(["Name", "Status", "Uptime"]).style(
        Style().fg(Color.cyan()).bold()
    )
    table_rows = [
        Row.from_strings(["nginx", "running", "14d"]),
        Row.from_strings(["postgres", "running", "21d"]),
        Row.from_strings(["redis", "degraded", "3h"]),
    ]
    frame.render_stateful_table(
        Table(
            table_rows,
            [Constraint.fill(1), Constraint.length(10), Constraint.length(8)],
            header=header,
        )
        .block(Block().bordered().title("Table"))
        .highlight_style(Style().fg(Color.yellow()).bold())
        .highlight_symbol("▶ "),
        middle[1],
        _table_state,
    )

    frame.render_widget(
        Sparkline()
        .data([10, 40, 20, 80, 55, 90])
        .max(100)
        .style(Style().fg(Color.cyan()))
        .block(Block().bordered().title("Sparkline")),
        rows[3],
    )

run_app(ui)

from pyratatui import (
    BarColorMode,
    BarGraph,
    BarGraphStyle,
    Block,
    CalendarDate,
    CalendarEventStore,
    Color,
    Constraint,
    Direction,
    Layout,
    Monthly,
    Paragraph,
    Popup,
    PopupState,
    QrCodeWidget,
    QrColors,
    Style,
    TextArea,
    Tree,
    TreeItem,
    TreeState,
    markdown_to_text,
    run_app,
)

popup = Popup("Press q to dismiss").title("Popup").style(Style().bg(Color.blue()))
popup_state = PopupState()

textarea = TextArea.from_lines(["Hello", "World"])
textarea.set_block(Block().bordered().title("TextArea"))

tree = Tree([
    TreeItem("src", [TreeItem("main.rs"), TreeItem("lib.rs")]),
    TreeItem("Cargo.toml"),
]).block(Block().bordered().title("Tree"))
tree_state = TreeState()
tree_state.select([0])

def ui(frame, _popup_state=popup_state, _ta=textarea, _tree=tree, _tree_state=tree_state):
    rows = (
        Layout()
        .direction(Direction.Vertical)
        .constraints([
            Constraint.length(12),
            Constraint.length(10),
            Constraint.fill(1),
        ])
        .split(frame.area)
    )
    top = (
        Layout()
        .direction(Direction.Horizontal)
        .constraints([
            Constraint.percentage(25),
            Constraint.percentage(25),
            Constraint.percentage(25),
            Constraint.fill(1),
        ])
        .split(rows[0])
    )
    middle = (
        Layout()
        .direction(Direction.Horizontal)
        .constraints([Constraint.fill(1), Constraint.length(28)])
        .split(rows[1])
    )

    qr_block = Block().bordered().title("QR Code")
    frame.render_widget(qr_block, top[0])
    frame.render_qrcode(
        QrCodeWidget("https://ratatui.rs").colors(QrColors.Inverted),
        qr_block.inner(top[0]),
    )

    store = CalendarEventStore.today_highlighted(Style().fg(Color.green()).bold())
    frame.render_widget(
        Monthly(CalendarDate.today(), store)
        .block(Block().bordered().title("Calendar"))
        .show_month_header(Style().bold())
        .show_weekdays_header(Style().italic()),
        top[1],
    )

    graph_block = Block().bordered().title("Bar Graph")
    frame.render_widget(graph_block, top[2])
    frame.render_widget(
        BarGraph([0.1, 0.4, 0.9, 0.6, 0.8])
        .bar_style(BarGraphStyle.Braille)
        .color_mode(BarColorMode.VerticalGradient)
        .gradient("turbo"),
        graph_block.inner(top[2]),
    )

    frame.render_stateful_popup(popup, top[3], _popup_state)

    frame.render_widget(
        Paragraph(markdown_to_text("# Hello\n\n**bold** _italic_ `code`"))
        .block(Block().bordered().title("Markdown")),
        middle[0],
    )
    frame.render_stateful_tree(_tree, middle[1], _tree_state)

    frame.render_textarea(_ta, rows[2])

run_app(ui)

import time
from pyratatui import Effect, EffectManager, Interpolation, Color, Terminal, Paragraph

mgr = EffectManager()
mgr.add(Effect.fade_from_fg(Color.black(), 1000, Interpolation.SineOut))
last = time.monotonic()

with Terminal() as term:
    while not (ev := term.poll_event(timeout_ms=16)) or ev.code != "q":
        now = time.monotonic()
        elapsed_ms = int((now - last) * 1000)
        last = now

        def ui(frame, _mgr=mgr, _ms=elapsed_ms):
            # Step 1 — render widgets
            frame.render_widget(Paragraph.from_string("Fading in…"), frame.area)
            # Step 2 — apply effects to the same buffer
            frame.apply_effect_manager(_mgr, _ms, frame.area)

        term.draw(ui)

from pyratatui import compile_effect, EffectManager

# DSL mirrors the Rust / tachyonfx expression syntax
effect = compile_effect("fx::coalesce(500)")
effect = compile_effect("fx::dissolve((800, BounceOut))")
effect = compile_effect("fx::fade_from_fg(Color::Black, (600, QuadOut))")
effect = compile_effect("fx::sweep_in(LeftToRight, 10, 5, Color::Black, (700, SineOut))")

mgr = EffectManager()
mgr.add(effect)

from pyratatui import CellFilter, Effect, Color

effect = Effect.fade_from_fg(Color.black(), 800)
effect.with_filter(CellFilter.text())                           # text cells only
effect.with_filter(CellFilter.inner(horizontal=1, vertical=1)) # inner area
effect.with_filter(CellFilter.fg_color(Color.cyan()))          # specific fg color
effect.with_filter(CellFilter.any_of([CellFilter.text(), CellFilter.all()]))

import asyncio
from pyratatui import AsyncTerminal, Gauge, Block, Style, Color

state = {"progress": 0}

async def background_worker():
    while state["progress"] < 100:
        await asyncio.sleep(0.1)
        state["progress"] += 2

async def main():
    worker = asyncio.create_task(background_worker())

    async with AsyncTerminal() as term:
        async for ev in term.events(fps=30):
            pct = state["progress"]

            def ui(frame, _pct=pct):
                frame.render_widget(
                    Gauge()
                    .percent(_pct)
                    .label(f"Loading… {_pct}%")
                    .style(Style().fg(Color.green()))
                    .block(Block().bordered().title("Progress")),
                    frame.area,
                )

            term.draw(ui)

            if ev and ev.code == "q":
                break
            if pct >= 100:
                break

    worker.cancel()

asyncio.run(main())

async for ev in term.events(fps=30.0, stop_on_quit=True):
    # ev is KeyEvent | None
    # None emitted each tick (use for animations / periodic updates)
    # stop_on_quit=True (opt-in) exits the loop automatically on "q" or Ctrl+C

from pyratatui import run_app, run_app_async, Paragraph

# Synchronous
def ui(frame):
    frame.render_widget(
        Paragraph.from_string("Hello!"),
        frame.area
    )

run_app(ui, on_key=lambda ev: ev.code == "q")

# Asynchronous
import asyncio

async def main():
    tick = 0
    def ui(frame):
        nonlocal tick
        frame.render_widget(Paragraph.from_string(f"Tick: {tick}"), frame.area)
        tick += 1
    await run_app_async(ui, fps=30, on_key=lambda ev: ev.code == "q")

asyncio.run(main())

class Terminal:
    def __enter__(self) -> Terminal
    def __exit__(self, ...) -> bool
    def draw(self, draw_fn: Callable[[Frame], None]) -> None
    def poll_event(self, timeout_ms: int = 0) -> KeyEvent | None
    def area(self) -> Rect
    def clear(self) -> None
    def hide_cursor(self) -> None
    def show_cursor(self) -> None
    def restore(self) -> None

class AsyncTerminal:
    async def __aenter__(self) -> AsyncTerminal
    async def __aexit__(self, ...) -> bool
    def draw(self, draw_fn: Callable[[Frame], None]) -> None
    async def poll_event(self, timeout_ms: int = 50) -> KeyEvent | None
    async def events(self, fps: float = 30.0, *, stop_on_quit: bool = False) -> AsyncIterator[KeyEvent | None]
    def area(self) -> Rect
    def clear(self) -> None
    def hide_cursor(self) -> None
    def show_cursor(self) -> None

class Frame:
    @property
    def area(self) -> Rect

    # Standard widgets (stateless)
    def render_widget(self, widget: object, area: Rect) -> None

    # Stateful widgets
    def render_stateful_list(self, widget: List, area: Rect, state: ListState) -> None
    def render_stateful_table(self, widget: Table, area: Rect, state: TableState) -> None
    def render_stateful_scrollbar(self, widget: Scrollbar, area: Rect, state: ScrollbarState) -> None
    def render_stateful_menu(self, widget: Menu, area: Rect, state: MenuState) -> None

    # Popups
    def render_popup(self, popup: Popup, area: Rect) -> None
    def render_stateful_popup(self, popup: Popup, area: Rect, state: PopupState) -> None

    # Text editor
    def render_textarea(self, ta: TextArea, area: Rect) -> None

    # Scroll view
    def render_stateful_scrollview(self, sv: ScrollView, area: Rect, state: ScrollViewState) -> None

    # QR code
    def render_qrcode(self, qr: QrCodeWidget, area: Rect) -> None

    # Effects
    def apply_effect(self, effect: Effect, elapsed_ms: int, area: Rect) -> None
    def apply_effect_manager(self, manager: EffectManager, elapsed_ms: int, area: Rect) -> None

    # Prompts
    def render_text_prompt(self, prompt: TextPrompt, area: Rect, state: TextState) -> None
    def render_password_prompt(self, prompt: PasswordPrompt, area: Rect, state: TextState) -> None

class Layout:
    def constraints(self, constraints: list[Constraint]) -> Layout
    def direction(self, direction: Direction) -> Layout
    def margin(self, margin: int) -> Layout
    def spacing(self, spacing: int) -> Layout
    def flex_mode(self, mode: str) -> Layout
    def split(self, area: Rect) -> list[Rect]

class Rect:
    x: int;  y: int;  width: int;  height: int
    right: int;  bottom: int;  left: int;  top: int
    def area(self) -> int
    def inner(self, horizontal: int = 1, vertical: int = 1) -> Rect
    def contains(self, other: Rect) -> bool
    def intersection(self, other: Rect) -> Rect | None
    def union(self, other: Rect) -> Rect

class Style:
    def fg(self, color: Color) -> Style
    def bg(self, color: Color) -> Style
    def bold(self) -> Style
    def italic(self) -> Style
    def underlined(self) -> Style
    def dim(self) -> Style
    def reversed(self) -> Style
    def hidden(self) -> Style
    def crossed_out(self) -> Style
    def slow_blink(self) -> Style
    def rapid_blink(self) -> Style
    def patch(self, other: Style) -> Style
    def add_modifier(self, modifier: Modifier) -> Style
    def remove_modifier(self, modifier: Modifier) -> Style

class Block:
    def title(self, title: str) -> Block
    def title_bottom(self, title: str) -> Block
    def bordered(self) -> Block                          # all four borders
    def borders(self, top, right, bottom, left) -> Block
    def border_type(self, bt: BorderType) -> Block       # Plain | Rounded | Double | Thick
    def style(self, style: Style) -> Block
    def border_style(self, style: Style) -> Block
    def title_style(self, style: Style) -> Block
    def padding(self, left, right, top, bottom) -> Block
    def title_alignment(self, alignment: str) -> Block

from pyratatui import (
    Terminal,
    TextPrompt,
    TextState,
    prompt_password,
    prompt_text,
)

# Blocking single-line text prompt (runs its own event loop)
value: str | None = prompt_text("Enter your name: ")
password: str | None = prompt_password("Password: ")

# Stateful inline prompts
state = TextState()
state.focus()

with Terminal() as term:
    term.hide_cursor()

    while state.is_pending():
        def ui(frame, _state=state):
            frame.render_text_prompt(TextPrompt("Search: "), frame.area, _state)

        term.draw(ui)
        ev = term.poll_event(timeout_ms=50)
        if ev:
            state.handle_key(ev)

    term.show_cursor()

if state.is_complete():
    print(state.value())
elif state.is_aborted():
    print("Prompt aborted.")