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 telaadmin/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:
- Polling declarativo — helico precisa re-consultar o servidor a cada 4s enquanto
synchronizingestá ativo ou há arquivos comis_processing: true. Middag não tem mecanismo declarativo para isso. - Confirmação honrada no frontend —
page_action.requires_confirmation: boolexiste em PHP mas o frontendDenseTableBlock.tsxignora e dispararouter.delete/postdireto. - Loading state em
page_action—page_action.disabled: boolexiste; faltaloading: boolpara botão ficar com spinner enquanto ação assíncrona do servidor está em curso. - 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. Hojerow_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'→ retornablock.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_contractcommeta.pollem um blocodense_tablenão quebra serialização JSON. - Frontend: com
poll.interval_ms = 4000e condição ativa, o bloco re-renderiza a cada 4s viarouter.reload({ only: [key] }). - Condição inativa → timer é limpo; nenhum request pendente.
- Unmount → timer é limpo.
- Dois blocos
dense_tablena mesma página com poll independente funcionam sem interferência (cada um recarrega só comonly: [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çãometa.poll)local_middag/classes/framework/shared/ui/region_builder.php(+ helperpoll(), 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: boolexiste 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_actioncomrequires_confirmation: truesem 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á — adicionarconfirm()builder)local_middag/classes/framework/contract/ui/page_action_interface.php(assinatura atualizada se aplicável)local_middag/ui/src/contracts/page-contract.ts(tipoPageActionganhaconfirmation?: {...})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.tsxou similar (novo, se não existir) — o reui já temalert-dialog.tsxedialog.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 inativodisabled 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: trueexibe spinner no lugar (ou antes) do ícone. -
loading: trueefetivamente desabilita o botão (sem precisar setardisabledtambém, opcional conveniência). -
loading: falseremove spinner. - Combinado com M1 (polling): servidor marca
loadingvia 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(tipoPageActionganhaloading?: 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
htmlem 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
- 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).
- ConfirmDialog global vs local:
<ConfirmDialogHost />montado uma vez no shell + store zustand; ou cada action embute seu dialog. Recomendação: host global. - 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. - Nome do hook
useServerPolling: manter, ou padronizar com outros hooks middag (ex.:usePoll,useIntervalReload)? Alinhar com convenção interna. - Backward compatibility:
page_actiontem vários campos opcionais novos. Qualquer código existente que construapage_actionvia construtor nomeado continua funcionando. Checar se há uso por posição.
Ordem sugerida de execução na sessão middag
- M2 primeiro (menor, quebra menos, testável independentemente).
- M3 logo depois (mesmo arquivo, incremento pequeno).
- 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:
- Em middag:
npm run build:reactpassa. - Em helico:
npm run build:reactainda passa (helico não depende do build de middag, mas deps transitivas podem ter mudado). - 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). - Refazer
admin_controller::index()do helico conforme exemplo acima. - Refazer
Index.tsxdo helico como thin wrapper deContractPage. - 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