Skip to content

Extensões no pagebuilder do localmiddag — solicitação do local_helico

Extensões no page_builder do local_middag — solicitação do local_helico

  • Data: 2026-04-23
  • Origem: sessão Claude do local_helico (piloto de migração Vue→React da tela admin/disciplina)
  • Tipo: brief para sessão separada em local_middag/
  • Status: rascunho para o mantenedor do middag validar

Contexto

O piloto local_helico começou assumindo uso do page_builder (ContractPage + page_builder PHP + dense_table block). Ao mapear os requisitos da tela admin/disciplina/Index e /Edit contra o que o middag entrega hoje, identificaram-se 4 gaps no page_builder que impedem o helico de migrar sem duplicar lógica:

  1. Polling declarativo — helico precisa re-consultar o servidor a cada 4s enquanto synchronizing está ativo ou há arquivos com is_processing: true. Middag não tem mecanismo declarativo para isso.
  2. Confirmação honrada no frontend — page_action.requires_confirmation: bool existe em PHP mas o frontend DenseTableBlock.tsx ignora e dispara router.delete/post direto.
  3. Loading state em page_action — page_action.disabled: bool existe; falta loading: bool para botão ficar com spinner enquanto ação assíncrona do servidor está em curso.
  4. rowAction condicional (visibilidade + disabled com razão) — helico tem "Processar" que só aparece na última versão e "Flashcards" que fica disabled com tooltip explicativo. Hoje row_action é estático ({id, label, href, method}), sem flags de visibility/disabled server-side.

Decisão do helico: adotar híbrido C — migrar Index para page_builder após as extensões M1+M2+M3 chegarem; Edit fica como componente React custom (form + tabela + 2 modais + regras é complexo demais para o modelo declarativo atual sem exagerar o escopo).

Extensões M4 (rowAction condicional) e as mudanças para suportar Edit ficam fora deste brief. Brief cobre M1, M2, M3 — o mínimo para Index migrar.

M1 — Polling declarativo

Problema

Após uma ação de sync/process disparada por Inertia, o cliente precisa re-carregar os dados periodicamente até o servidor indicar que a operação terminou. Hoje isso é feito em componente React custom (useServerPolling hook + useEffect). Queremos mecanismo declarativo via page_contract.

API proposta (PHP)

Em framework/shared/ui/block_descriptor.php, nada muda — meta: array<string, mixed> já aceita payload livre. Adiciona-se convenção:

new block_descriptor(
    type: 'dense_table',
    key: 'disciplinas',
    data: [...],
    meta: [
        'poll' => [
            'interval_ms' => 4000,
            // modo 1: sempre que bloco renderizar
            'active' => 'always',
            // modo 2: campo boolean na meta do bloco
            'active' => ['meta_field' => 'synchronizing'],
            // modo 3: ao menos uma row com campo truthy
            'active' => ['any_row' => 'is_processing'],
            // modo 4: combinação (OR)
            'active' => [
                'any' => [
                    ['meta_field' => 'synchronizing'],
                    ['any_row' => 'is_processing'],
                ],
            ],
        ],
    ],
);

Helper opcional no region_builder:

$region->dense_table('disciplinas', '', $data)
    ->poll(interval_ms: 4000, active_any: [
        ['meta_field' => 'synchronizing'],
        ['any_row' => 'is_processing'],
    ]);

Alternativa mais simples (MVP): aceitar apenas o modo 4 (array de condições OR) + interval_ms. Modos 1/2/3 são açúcar.

API proposta (React)

Em local_middag/ui/src/system/blocks/DenseTableBlock.tsx, após resolução do data:

import { useServerPolling } from '@/lib/hooks/useServerPolling';
import { router } from '@inertiajs/core';

const poll = block.meta?.poll as PollSpec | undefined;
const isPollActive = poll ? evaluatePollActive(poll, block) : false;

useServerPolling({
    active: isPollActive && Boolean(poll),
    intervalMs: poll?.intervalMs ?? 4000,
    onTick: () => {
        router.reload({ only: [block.key], preserveState: true, preserveScroll: true });
    },
});

Helper evaluatePollActive(poll, block):

  • Para cada condição em poll.active.any:
    • meta_field: 'x' → retorna Boolean(block.meta.x)
    • any_row: 'y' → retorna block.data.rows.some(r => Boolean(r[y]))
  • Retorna OR de todas

Criar hook useServerPolling em lib/hooks/useServerPolling.ts (mover da cópia que o helico tem, ou criar do zero):

import { useEffect, useRef } from 'react';

export function useServerPolling({ active, intervalMs, onTick }: {
    active: boolean;
    intervalMs: number;
    onTick: () => void | Promise<void>;
}): void {
    const timerRef = useRef<number | null>(null);
    const onTickRef = useRef(onTick);

    useEffect(() => { onTickRef.current = onTick; }, [onTick]);

    useEffect(() => {
        if (!active) {
            if (timerRef.current) {
                window.clearInterval(timerRef.current);
                timerRef.current = null;
            }
            return;
        }
        if (timerRef.current) return;
        timerRef.current = window.setInterval(() => void onTickRef.current(), intervalMs);
        return () => {
            if (timerRef.current) {
                window.clearInterval(timerRef.current);
                timerRef.current = null;
            }
        };
    }, [active, intervalMs]);
}

Critérios de aceitação

  • Backend: construir um page_contract com meta.poll em um bloco dense_table não quebra serialização JSON.
  • Frontend: com poll.interval_ms = 4000 e condição ativa, o bloco re-renderiza a cada 4s via router.reload({ only: [key] }).
  • Condição inativa → timer é limpo; nenhum request pendente.
  • Unmount → timer é limpo.
  • Dois blocos dense_table na mesma página com poll independente funcionam sem interferência (cada um recarrega só com only: [seu key]).
  • Guard: request Inertia inflight não dispara o próximo tick (opcional, mas evita pile-up de requests).

Arquivos afetados (estimativa)

  • local_middag/classes/framework/shared/ui/block_descriptor.php (0 mudanças — só documentar a convenção meta.poll)
  • local_middag/classes/framework/shared/ui/region_builder.php (+ helper poll(), opcional)
  • local_middag/ui/src/lib/hooks/useServerPolling.ts (novo, ~30 LOC)
  • local_middag/ui/src/system/blocks/DenseTableBlock.tsx (+ 15 LOC para wiring)

Complexidade estimada

Baixa-média. 1 dia de dev.


M2 — Confirmação honrada no frontend

Problema

  • page_action.requires_confirmation: bool existe no VO PHP desde ADR-807, mas o frontend nunca implementou o fluxo.
  • Aplicações que tentam usar (helico, outros plugins futuros) precisam envolver manualmente as ações com <ConfirmDialog>, derrotando o ponto de ter a flag declarativa.

API proposta (PHP)

Estender framework/shared/ui/page_action.php:

readonly class page_action implements page_action_interface
{
    public function __construct(
        public string $id,
        public string $label,
        public string $intent,
        public ?string $href = null,
        public ?string $method = null,
        public ?string $icon = null,
        public bool $requires_confirmation = false,
        public bool $disabled = false,
        // --- novos campos (todos opcionais) ---
        public ?string $confirmation_title = null,
        public ?string $confirmation_message = null,
        public ?string $confirmation_confirm_label = null, // default "Confirmar"
        public ?string $confirmation_cancel_label = null,  // default "Cancelar"
        public ?string $confirmation_intent = null,        // 'primary' | 'danger'; default 'primary'
    ) {}

    public function jsonSerialize(): array
    {
        $data = [
            'id' => $this->id,
            'label' => $this->label,
            'intent' => $this->intent,
        ];

        if ($this->href !== null) $data['href'] = $this->href;
        if ($this->method !== null) $data['method'] = $this->method;
        if ($this->icon !== null) $data['icon'] = $this->icon;
        if ($this->disabled) $data['disabled'] = true;

        if ($this->requires_confirmation) {
            $data['confirmation'] = array_filter([
                'title' => $this->confirmation_title,
                'message' => $this->confirmation_message,
                'confirmLabel' => $this->confirmation_confirm_label ?? 'Confirmar',
                'cancelLabel' => $this->confirmation_cancel_label ?? 'Cancelar',
                'intent' => $this->confirmation_intent ?? 'primary',
            ], fn($v) => $v !== null);
        }

        return $data;
    }
}

Compatibilidade: todos os novos campos são opcionais. Código que já usa requires_confirmation: true sem detalhes continua funcionando (dialog usa defaults).

Backend helper no page_builder:

page_builder::action(
    id: 'sync',
    label: 'Sincronizar arquivos',
    intent: 'primary',
    href: '/sync/start',
    method: 'post',
    icon: 'refresh-cw',
)->confirm(
    title: 'Confirmação de sincronização',
    message: 'Você está prestes a iniciar a sincronização dos arquivos.',
)

Adicionar método fluent ->confirm(title, message, confirm_label = 'Confirmar', intent = 'primary') que seta requires_confirmation = true + campos.

API proposta (React)

Onde o page_action é renderizado (provavelmente no Shell — AdminShell.tsx ou shell equivalent que mostra a barra de ações da página), e onde rowAction é despachado (DenseTableBlock.tsx), wrappar o handler:

// Pseudo — dependendo de onde as actions são renderizadas hoje
function handleAction(action: PageAction) {
    const execute = () => {
        if (action.href) {
            const method = (action.method ?? 'get').toLowerCase() as 'get'|'post'|'put'|'delete';
            if (method === 'get') router.visit(action.href);
            else router[method](action.href, {}, { preserveState: true });
        }
    };

    if (action.confirmation) {
        openConfirmDialog({
            title: action.confirmation.title ?? 'Confirmação',
            message: action.confirmation.message ?? 'Confirma a ação?',
            confirmLabel: action.confirmation.confirmLabel ?? 'Confirmar',
            cancelLabel: action.confirmation.cancelLabel ?? 'Cancelar',
            intent: action.confirmation.intent ?? 'primary',
            onConfirm: execute,
        });
    } else {
        execute();
    }
}

Onde openConfirmDialog é um mecanismo global (ex.: componente <ConfirmDialogHost /> montado uma vez no shell, com um store/context para disparar). Alternativa: cada action button embutir seu próprio <ConfirmDialog> local.

Recomendação: <ConfirmDialogHost /> global no shell, controlado por um store (Zustand, ou simples provider Context). Permite reutilização.

Critérios de aceitação

  • Backend: page_action com requires_confirmation: true sem campos adicionais → frontend abre dialog com labels default em pt-BR.
  • Backend: com título/mensagem/labels customizados → dialog exibe customizações.
  • Backend: confirmation_intent = 'danger' → botão de confirmar vermelho (variant=“destructive”).
  • Frontend: cancelar fecha o dialog sem disparar a ação.
  • Frontend: confirmar fecha o dialog e dispara a ação (Inertia request).
  • Aplicar tanto em page_action quanto em rowAction de dense_table.

Arquivos afetados

  • local_middag/classes/framework/shared/ui/page_action.php (+ 5 campos + jsonSerialize)
  • local_middag/classes/framework/shared/ui/page_builder.php (ou onde a fluent action factory está — adicionar confirm() builder)
  • local_middag/classes/framework/contract/ui/page_action_interface.php (assinatura atualizada se aplicável)
  • local_middag/ui/src/contracts/page-contract.ts (tipo PageAction ganha confirmation?: {...})
  • local_middag/ui/src/system/blocks/DenseTableBlock.tsx (wrap rowAction dispatch com confirm flow)
  • local_middag/ui/src/system/shell/AdminShell.tsx (ou onde page_action é renderizado — wrap page action dispatch)
  • local_middag/ui/src/components/reui/alert-dialog.tsx ou similar (novo, se não existir) — o reui já tem alert-dialog.tsx e dialog.tsx; aproveitar um deles

Complexidade estimada

Baixa. 4-6 horas de dev.


M3 — Loading state em page_action

Problema

Botão “Sincronizar arquivos” do helico precisa mostrar spinner enquanto sync está em curso no servidor. Hoje page_action.disabled resolve “desabilitar botão” mas não mostra feedback visual de “em progresso”.

API proposta (PHP)

Estender page_action.php:

public function __construct(
    ...
    public bool $disabled = false,
    public bool $loading = false,  // NOVO
    ...
) {}

public function jsonSerialize(): array
{
    $data = [...];
    if ($this->loading) $data['loading'] = true;
    ...
}

Uso típico:

page_builder::action(
    id: 'sync',
    label: 'Sincronizar arquivos',
    icon: 'refresh-cw',
    method: 'post',
    href: '/sync/start',
)
->loading($synchronizing)  // bool vindo do server state
->disabled($synchronizing)  // enquanto sincronizando, botão inativo

disabled e loading podem conviver. loading=true geralmente implica visual de “processando” (spinner + texto).

API proposta (React)

No renderizador de page action:

function ActionButton({ action }: { action: PageAction }) {
    return (
        <Button
            variant={variantFor(action.intent)}
            disabled={action.disabled || action.loading}
            onClick={() => handleAction(action)}
        >
            {action.loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
            {!action.loading && action.icon && <Icon name={action.icon} className="mr-2 h-4 w-4" />}
            {action.label}
        </Button>
    );
}

Critérios de aceitação

  • loading: true exibe spinner no lugar (ou antes) do ícone.
  • loading: true efetivamente desabilita o botão (sem precisar setar disabled também, opcional conveniência).
  • loading: false remove spinner.
  • Combinado com M1 (polling): servidor marca loading via state field, polling atualiza, spinner aparece/some automaticamente.

Arquivos afetados

  • local_middag/classes/framework/shared/ui/page_action.php (+ 1 campo)
  • local_middag/ui/src/contracts/page-contract.ts (tipo PageAction ganha loading?: boolean)
  • Renderizador de page action (mesmo arquivo afetado no M2)

Complexidade estimada

Trivial. 1-2 horas.


Exemplo consolidado — como helico usa depois

Após M1+M2+M3, o admin_controller::index() do helico:

public function index(): Response
{
    $this->set_require_login();
    $this->set_page_layout('admin');
    $this->set_page_title('Disciplinas');
    $this->set_page_heading('Disciplinas');
    $this->use_react_inertia();

    $fullname = $this->request->query->get('fullname', '');
    $page = (int) $this->request->query->get('page', 1);
    $perpage = (int) $this->request->query->get('per_page', 10);

    $service = middag::get(discipline_service::class);
    [$rows, $total] = $service->list($fullname, false, $page - 1, $perpage);
    $synchronizing = (int) config_support::get_config('local_helico', 'manual_sync_disciplina') === 1;

    $contract = page_builder::page('helico.disciplinas.index')
        ->shell('admin')
        ->title('Disciplinas')
        ->layout('stack')
        ->actions([
            page_builder::action(
                id: 'sync',
                label: 'Sincronizar arquivos',
                intent: 'primary',
                href: '/local/helico/index.php/helico/content/api/v1/sync/start',
                method: 'post',
                icon: 'refresh-cw',
            )
                ->confirm(
                    title: 'Confirmação de sincronização',
                    message: 'Você está prestes a iniciar a sincronização dos arquivos.',
                )
                ->loading($synchronizing)
                ->disabled($synchronizing)
                ->build(),
        ])
        ->region('content', fn (region_builder $r) => $r
            ->dense_table('disciplinas', '', [
                'columns' => [
                    ['key' => 'id', 'label' => '#', 'sortable' => false],
                    ['key' => 'idnumber', 'label' => 'ID number'],
                    ['key' => 'fullname', 'label' => 'Nome completo'],
                    ['key' => 'status', 'label' => 'Status', 'variant' => 'badge'],
                    ['key' => 'lastprocess', 'label' => 'Último processamento'],
                ],
                'rows' => array_map(fn ($row) => [
                    ...$row,
                    // converter status HTML para structured {label, tone}
                    'status' => $this->format_status($row),
                ], $rows),
                'pagination' => [
                    'page' => $page,
                    'perPage' => $perpage,
                    'total' => $total,
                    'lastPage' => (int) ceil($total / $perpage),
                ],
                'sort' => ['column' => 'created_at', 'direction' => 'desc'],
                'searchPlaceholder' => 'Digite o nome',
                'filters' => ['available' => [], 'applied' => []],
                'rowActions' => [
                    ['id' => 'edit', 'label' => 'Editar', 'icon' => 'pencil', 'href' => '{urledit}'],
                    [
                        'id' => 'delete',
                        'label' => 'Excluir',
                        'icon' => 'trash-2',
                        'method' => 'delete',
                        'href' => '/local/helico/index.php/helico/content/api/v1/disciplinas/{id}',
                        'confirmation' => [
                            'title' => 'Confirmação de exclusão',
                            'message' => 'Você está prestes a excluir esse registro. Essa ação não poderá ser desfeita.',
                            'confirmLabel' => 'Excluir',
                            'intent' => 'danger',
                        ],
                    ],
                ],
                'meta' => [
                    'synchronizing' => $synchronizing,
                    'poll' => [
                        'interval_ms' => 4000,
                        'active' => [
                            'any' => [
                                ['meta_field' => 'synchronizing'],
                                ['any_row' => 'is_processing'],
                            ],
                        ],
                    ],
                ],
            ]),
        )
        ->build();

    return $this->inertia('admin/disciplina/Index', ['contract' => $contract]);
}

E o Index.tsx vira:

import type { ReactElement } from 'react';
import { ContractPage } from '@middag/runtime/ContractPage';
import type { PageContract } from '@middag/contracts/page-contract';

interface Props { contract: PageContract; }

export default function DisciplinaIndexPage({ contract }: Props): ReactElement {
    return <ContractPage contract={contract} />;
}

Todo o código de polling, modal de delete, modal de sync, filtro, paginação, tooltip, etc. desaparece de helico. Vive no middag.

Não-escopo (explícito)

  • M4 (rowAction condicional visibility/disabled com razão) — Edit do helico precisa, mas Edit fica custom React no piloto. Pode entrar em sprint futuro.
  • Layout form+tabela híbrido — necessário para migrar Edit; fora deste brief.
  • Variant html em colunas — helico vai migrar status para structured {label, tone} em vez de HTML arbitrário. Se outro plugin precisar HTML, pode entrar em brief separado.
  • Testes automatizados das extensões — a sessão middag decide se introduz testes PHPUnit/Vitest ou só UAT.

Open questions para a sessão middag

  1. Condição de poll — modo 1/2/3/4: aceitar só modo 4 (OR array) no MVP, ou suportar todos os 4 açúcares sintáticos? Recomendação: só modo 4 (mais simples, expressivo).
  2. ConfirmDialog global vs local: <ConfirmDialogHost /> montado uma vez no shell + store zustand; ou cada action embute seu dialog. Recomendação: host global.
  3. Onde action.loading é computado: sempre pelo backend (server state)? Ou cliente também pode forçar local (ex.: antes do Inertia response voltar)? Recomendação: apenas backend; UI decorativa pode viver fora do contract.
  4. Nome do hook useServerPolling: manter, ou padronizar com outros hooks middag (ex.: usePoll, useIntervalReload)? Alinhar com convenção interna.
  5. Backward compatibility: page_action tem vários campos opcionais novos. Qualquer código existente que construa page_action via construtor nomeado continua funcionando. Checar se há uso por posição.

Ordem sugerida de execução na sessão middag

  1. M2 primeiro (menor, quebra menos, testável independentemente).
  2. M3 logo depois (mesmo arquivo, incremento pequeno).
  3. M1 por último (mais novo, toca em DenseTableBlock).

Cada extensão pode ser um commit (ou um conjunto menor) no middag. Build React do middag (npm run build:react) deve passar após cada.

Verificação cross-plugin

Após as 3 extensões estarem prontas no middag:

  1. Em middag: npm run build:react passa.
  2. Em helico: npm run build:react ainda passa (helico não depende do build de middag, mas deps transitivas podem ter mudado).
  3. Em helico: reimportar os novos símbolos via @middag/* OU copiar atualizações para helico owned copy (helico hoje tem cópia local dos componentes reui; decisão entre re-sincronizar vs reimport fica com o integrador).
  4. Refazer admin_controller::index() do helico conforme exemplo acima.
  5. Refazer Index.tsx do helico como thin wrapper de ContractPage.
  6. UAT no Moodle: carregar /local/helico/index.php/disciplinas, exercitar filtro, paginação, delete (com modal), sync (com modal + loading + polling).

Referências

  • ADR-807 (local_middag/docs/vault/adrs/adr-807_frontend_interface_architecture_and_dynamic_layout.md) — arquitetura base do page_builder
  • ref-807-02 (local_middag/docs/vault/adrs/ref/ref-807-02-page-builder-and-crud.md) — CRUD builder + dense_table
  • Spec do piloto helico — local_helico/docs/_archive/specs/2026-04-23-pilot-disciplina-react-migration-design.md
  • Plano do piloto helico — local_helico/docs/_archive/plans/2026-04-23-pilot-disciplina-react-migration.md
Navigation

Type to search…

↑↓ navigate↵ selectEsc close