Imported from jrdiniz/flask-boilerplate (app/blueprints/webui/AGENTS.md). Install upstream with npx skills add jrdiniz/flask-boilerplate --skill webui. Copyright stays with the author.

AGENTS.md — Blueprint Webui

Propósito

Blueprint de interface web — ponto de entrada principal da aplicação. Responsável por renderizar as páginas HTML da aplicação utilizando Bootstrap 5, Bootstrap Icons e HTMX.

Estrutura

app/blueprints/webui/
├── AGENTS.md        # Este arquivo
├── __init__.py      # Objeto `bp` (Blueprint) + registro de URL rules
├── webui.py         # View functions
└── templates/       # Templates Jinja2 do blueprint
    └── index.html   # Página inicial

Rotas

Templates

O template index.html estende base.html e ocupa o bloco content. Templates específicos do blueprint ficam no diretório templates/ do próprio blueprint (não no diretório global app/templates/).

Convenções

Bootstrap 5 + Bootstrap Icons

Todo componente de interface deve utilizar classes Bootstrap 5. Ícones devem usar Bootstrap Icons:

<i class="bi bi-house"></i>
<button class="btn btn-primary"><i class="bi bi-save"></i> Salvar</button>

Nunca usar CSS customizado inline se o Bootstrap já oferece o componente equivalente.

HTMX obrigatório

Toda interatividade deve ser implementada com atributos HTMX:

<!-- Navegação parcial -->
<a hx-get="/pagina" hx-target="#conteudo" hx-push-url="true">Ir</a>

<!-- Formulário com submit via HTMX -->
<form hx-post="/salvar" hx-target="#resultado" hx-swap="outerHTML">
    <input type="text" name="nome" class="form-control">
    <button type="submit" class="btn btn-primary">Enviar</button>
</form>

<!-- Atualização dinâmica -->
<div hx-get="/atualizar" hx-trigger="every 5s"></div>

Sem Flask-WTF

Formulários devem ser criados com HTML puro + HTMX. Não utilizar Flask-WTF ou {{ form.field }}. Validar dados manualmente na view e retornar erros como HTML parcial.

# Correto: validação manual
def salvar():
    nome = request.form.get("nome", "").strip()
    if not nome:
        return '<div class="alert alert-danger">Nome é obrigatório</div>'
    # processar...
    return '<div class="alert alert-success">Salvo com sucesso</div>'

Navegação parcial

Ao criar novas páginas, renderizar apenas o conteúdo parcial quando acessadas via HTMX. Usar request.headers.get("HX-Request") para detectar requisições HTMX:

def pagina():
    template = "pagina.html"
    if request.headers.get("HX-Request"):
        return render_template(template)  # Retorna apenas o conteúdo
    return render_template(template)      # Fallback para página completa

Como estender

1. Nova view: Adicionar função em webui.py
2. Registrar rota: Adicionar add_url_rule() no __init__.py
3. Novo template: Criar arquivo .html em templates/ do blueprint

Exemplo — adicionando rota /sobre:

# webui.py
def sobre():
    return render_template("sobre.html")

# __init__.py
from .webui import sobre
sobre.methods = ["GET"]
bp.add_url_rule("/sobre", view_func=sobre)