Digite para filtrar as páginas da documentação.

    Termfy

    termfy-tui

    Use a termfy-tui para criar telas com OpenTUI no seu binário. Veja o tratamento de teclas, a carga assíncrona e os testes por frames nos dois temas da TUI.

    A skill termfy-tui cria e revisa as screens da TUI do seu binário com a API imperativa do OpenTUI Core. Ela monta o layout em células e trata a navegação por teclado e por mouse, mantendo o foco no item selecionado. Nas telas que consultam serviços, também trata o carregamento assíncrono e libera os recursos ao sair da aba. No fim, você tem uma screen registrada como aba, com número e ícone, com estados de carregando, vazio, erro e pronto, testada por teclas, por clique e por frames nas três faixas de largura. A conferência visual cobre os temas terminal, night e day.

    Quando usar

    • Você quer uma aba nova, como a screen orders com a lista de pedidos.
    • Uma screen existente precisa de navegação por teclado, mouse, rolagem ou um campo de formulário.
    • A tela precisa de ícones de papel e de uma barra de ações clicável.
    • A tela consulta uma API e você precisa tratar carregamento, erro e respostas que chegam fora de ordem.
    • Uma screen trava, vaza timers ou deixa o terminal sujo ao sair.

    Para entregar a screen junto com o command e a tool do mesmo recurso, use termfy-command-set. A chamada HTTP fica no client da termfy-api: a screen apresenta o resultado.

    Como pedir

    Para uma aba nova:

    Use a skill termfy-tui para criar a screen orders, que lista os pedidos da loja e mostra o pedido selecionado ao apertar Enter.

    Para uma tela que consulta um serviço:

    Use a skill termfy-tui para a screen orders carregar ao entrar na aba, com r para recarregar e mensagem própria quando a API falhar.

    Para revisar uma tela existente:

    Use a skill termfy-tui para revisar a screen orders: a lista some quando troco de aba e volto.

    O que a skill faz

    1. Confere o Git e lê a spec aberta em specs/: a screen na Surface, o Behavior com teclas e estados, o Design e os itens #termfy-tui.
    2. Confere a versão instalada de @opentui/core no lock antes de usar qualquer API.
    3. Lê src/tui/index.ts, src/tui/screen.ts, src/tui/components.ts, src/tui/theme.ts e src/tui/screens/index.ts. Mostra um plano curto com arquivos, comportamentos e verificações.
    4. Escolhe um dos cinco padrões de references/screen-patterns.md e adapta só o necessário: lista e detalhe, painel de status, formulário por diálogos, visualizador de documento e tela de progresso.
    5. Cria src/tui/screens/<id>.ts, compõe para wide, medium e compact com ctx.layout(), declara icon e as actions da tela e registra a screen em src/tui/screens/index.ts. Para abrir direto na aba, acrescenta o id em tui.initialTab de src/config/settings.ts e em --tab de src/cli/commands/tui.ts.
    6. Liga cada comando a uma ação, com tecla, clique e entrada na paleta na mesma função. Testa a lógica isolada, depois a screen com createTestRenderer e por fim a navegação com mountTui, com tecla, clique e diálogos.
    7. Confere terminal, night e day em 60×16, 80×24 e 120×32.
    8. Passa a references/quality-checklist.md linha a linha, atualiza docs/tui.md, roda bun run validate e marca [x] nos itens.

    Padrões de tela e checklist

    references/screen-patterns.md traz cinco composições. Cada uma descreve quando usar, os componentes, as teclas, a composição em wide, medium e compact e como testar.

    Padrão Uso
    lista e detalhe coleção com seleção e painel de leitura, com table e keyValueTable
    painel de status resumo de saúde, versão ou configuração atual
    formulário por diálogos poucos campos, editados com confirm, prompt e choose
    visualizador de documento aba de documentação com índice e Markdown
    tela de progresso operação longa com spinner e progressBar

    references/quality-checklist.md é a conferência antes de declarar a tela pronta: foco visível, estados vazio, carregando e erro, layout a partir de 60×16, ação com tecla, clique e paleta, confirmação antes de apagar, toast no resultado, resumo em ctx.status, contraste nos três temas, glifo só em icons.ts, segredo fora do frame, watch para arquivo lido e timers parados em onLeave e onPause.

    Exemplo

    A screen orders recebe a função de carga pela factory. Assim cada montagem tem o próprio estado e o teste injeta uma carga local:

    import { BoxRenderable, TextRenderable } from "@opentui/core";
    import { listPanel } from "../components.ts";
    import type { Screen, ScreenAction, ScreenContext } from "../screen.ts";
    import { listOrders, type Order } from "../../api/shop.ts";
    type Load = () => Promise<{ items: Order[] }>;
    export function createOrdersScreen(load: Load = () => listOrders({ limit: 50 })): Screen {
    let root: BoxRenderable | undefined;
    let status: TextRenderable | undefined;
    let list: ReturnType<typeof listPanel> | undefined;
    let orders: Order[] = [];
    let generation = 0;
    const show = (ctx: ScreenContext, items: Order[]) => {
    if (!root) return;
    if (list) { root.remove(list.box); list.box.destroyRecursively(); }
    orders = items;
    list = listPanel(ctx.renderer, ctx.theme, {
    title: "Orders",
    items: items.map((o) => `${o.id} ${o.status}`),
    onSelect: (i) => { if (status) status.content = `Order ${orders[i]?.id} selected`; },
    });
    root.add(list.box, 0);
    };
    const reload = async (ctx: ScreenContext) => {
    const current = ++generation;
    if (status) status.content = "Loading orders...";
    try {
    const page = await load();
    if (current !== generation) return;
    show(ctx, page.items);
    if (status) status.content = page.items.length ? "Enter selects an order" : "No orders";
    } catch {
    if (current === generation && status) status.content = "Unable to load orders. Press r to retry.";
    }
    };
    const actions: ScreenAction[] = [
    { keys: ["up", "k"], label: "↑/k", description: "up", run: () => list?.move(-1) },
    { keys: ["down", "j"], label: "↓/j", description: "down", run: () => list?.move(1) },
    {
    keys: ["return", "enter"],
    label: "Enter",
    description: "select",
    icon: "select",
    run: () => {
    const index = list?.selected() ?? -1;
    if (index >= 0) list?.select(index);
    },
    },
    { keys: ["r"], description: "reload", icon: "refresh", run: (ctx) => { void reload(ctx); } },
    ];
    return {
    id: "orders",
    title: "Orders",
    icon: "list",
    description: "Shop orders",
    actions,
    mount: (ctx) => {
    root = new BoxRenderable(ctx.renderer, { flexDirection: "column", flexGrow: 1 });
    status = new TextRenderable(ctx.renderer, { content: "", height: 1, flexShrink: 0, fg: ctx.theme.textDim });
    root.add(status);
    ctx.renderer.once("destroy", () => { generation++; });
    return root;
    },
    onEnter: (ctx) => { void reload(ctx); },
    onLeave: () => { generation++; },
    };
    }

    O registro entra em src/tui/screens/index.ts como [overviewScreen, createOrdersScreen(), aboutScreen]. Com orders em tui.initialTab e em --tab, a aba abre direto:

    Terminal
    mycli tui --tab orders
    mycli config set tui.initialTab orders

    Trecho do frame em 80×24, depois da carga e de uma tecla j:

    ╭ Orders ──────────────────────────────────────────╮
    │ o1 open │
    │ > o7 paid │
    ╰──────────────────────────────────────────────────╯
    Enter selects an order

    O teste espera a carga controlada terminar, sem pausa fixa:

    const setup = await createTestRenderer({ width: 80, height: 24 });
    (screens as Screen[]).push(createOrdersScreen(async () => ({
    items: [{ id: "o1", status: "open" }, { id: "o7", status: "paid" }],
    })));
    const closed = mountTui(setup.renderer, { initialTab: "orders" }, themes.night);
    try {
    await setup.waitForFrame((frame) => frame.includes("o7 paid"));
    setup.mockInput.pressKey("j");
    await setup.renderOnce();
    expect(setup.captureCharFrame()).toContain("> o7 paid");
    setup.mockInput.pressKey("q");
    await closed;
    } finally { setup.renderer.destroy(); }

    Regras que a skill segue

    • OpenTUI imperativo. A aba usa @opentui/core direto, sem React ou Solid, porque o host já entrega renderer e tema prontos.
    • Uma screen por arquivo, com factory. Estado no escopo do módulo vaza seleção entre duas montagens ou dois testes.
    • Componentes compartilhados. panel, table, listPanel, stateView, spinner, progressBar, link, keyValueTable, heading, dim e spacer mantêm o visual igual entre abas. spacer(renderer, height) não recebe tema.
    • Ação única para tecla, clique e paleta. Cada comando é uma ScreenAction com keys, description, icon e run. O botão, a linha de tabela ou de lista e a entrada da paleta chamam a mesma função.
    • Layout por faixa. A tela lê ctx.layout() e compõe para wide, medium e compact. O shell remonta a tela quando a faixa muda.
    • Diálogo no lugar de formulário. Um ou dois campos usam ctx.prompt, ctx.choose e ctx.confirm. Efeito destrutivo usa danger e valor oculto usa secret.
    • Resumo e toast. ctx.status mostra o resumo da tela e ctx.notify mostra o resultado de cada ação.
    • Ícones de ctx.icons. Nenhum glifo de papel fixo na screen, a key tui.icons troca o conjunto nerd, unicode ou ascii.
    • Mouse e teclado no mesmo efeito. O clique, o hover e a roda passam pela mesma ação da tecla. O teste usa setup.mockMouse.
    • Cores de ctx.theme. Cor fixa no código quebra uma das paletas. No tema terminal, cada cor é uma referência à paleta do terminal.
    • mount síncrono. mount cria os nós. O trabalho ativo começa em onEnter e para em onLeave.
    • Arquivo observado. watch() lista os arquivos que a tela lê. O shell recarrega a tela quando outro processo muda um deles e avisa no toast.
    • Pausa no foco. onPause para timers e onResume retoma. ctx.motion governa a animação curta de diálogos e toasts.
    • Cleanup em onLeave. O shell chama onLeave na troca de aba e no encerramento, então pare timers, assinaturas e consultas ali.
    • A aplicação é dona do renderer. A screen sai com ctx.quit(), sem process.exit(), sem outro renderer e sem escrever em stdout.
    • onKey devolve true só para tecla consumida. Assim q, ?, Tab, as setas laterais e os dígitos continuam trocando de aba e encerrando.
    • Respostas antigas descartadas. O contador de geração impede que uma carga lenta substitua uma mais nova ou altere uma aba que já saiu.
    • Mensagem própria no erro. A screen não mostra String(error) da API, que pode trazer detalhes internos do serviço.
    • Serviço compartilhado. A screen chama o mesmo client do CLI e do MCP, sem duplicar autenticação nem HTTP.

    O que ela entrega

    A skill relata os arquivos alterados, as versões conferidas, as teclas, as ações, os estados cobertos, as dimensões ensaiadas e um frame real capturado. Separa testes executados, exemplos só compilados e comportamentos não exercitados.

    Arquivo Mudança
    src/tui/screens/<id>.ts screen nova ou revisada
    src/tui/screens/index.ts screen na lista de abas
    src/config/settings.ts id em tui.initialTab, quando abre direto
    src/cli/commands/tui.ts id nos valores de --tab, idem
    tests/ testes com createTestRenderer e mountTui
    docs/tui.md teclas e uso da aba

    Próxima skill

    Se a screen trouxe uma preferência nova, declare a key com termfy-config. Para expor o mesmo recurso a agentes, siga com termfy-mcp.

    Planos Promovaweb

    Tire seus projetos do papel

    O Plano Martech cobre automação e atendimento. O Plano IA Makers acrescenta desenvolvimento com IA, enquanto o Plano Founders trata de gestão de negócios. Todos são anuais.

    Plano Martech

    Para conectar automação, marketing e atendimento com infraestrutura própria.

    R$ 897

    R$ 597/ano

    • Grade de automação, atendimento, marketing e análise de indicadores
    • Instalador Exclusivo Promovaweb
    • n8n, Evolution API, Chatwoot e Mautic
    • Trilha DevOps incluída
    • Encontros ao vivo (terça e quinta)
    • Comunidade e acompanhamento
    Conhecer o plano

    Plano Founders

    Plano anual para fazer um projeto de tecnologia avançar, com 90 dias de mentoria intensiva. R$ 1.997 à vista ou até 10x de R$ 219 no cartão.

    R$ 1.997/ano

    • 12 meses de acesso ao Founders
    • 90 dias de mentoria intensiva, um encontro por dia útil
    • Dia de conteúdo (terça e quinta) e War Room (segunda, quarta e sexta)
    • Encontro semanal em grupo após a fase intensiva
    • Formação Vibe Coding incluída no plano anual
    • Consultoria individual de até duas horas (bônus)
    Conhecer o plano