# Plano 10 — Layout Engine com Slots Configuráveis
> **Milestone:** M3 · **Depende de:** 09 · **Habilita:** 11–14
> **Objetivo:** definir a estrutura fundamental do front-end como uma **casca
> configurável**: o layout declara *slots*; módulos injetam conteúdo; o CMS
> reordena/oculta/preenche slots sem deploy.
---
## 1. Conceito
O layout é composto por **presets** (estrutura macro) + **slots** (pontos de
extensão nomeados). O módulo **não** conhece o template do portal: ele declara
"quero aparecer no slot `home.destaques`" e o Layout Engine resolve.
```
@slot('main.content') ... @endslot
@slot('main.left') ... @endslot
```
- **Preset** (Enum `LayoutPreset`): quais regiões existem (header/footer/sidebars) e o grid.
- **Slot**: ponto nomeado dentro de uma região (ex.: `header.search`, `home.destaques`,
`footer.links`, `main.after`).
- **SlotRegistry**: em runtime, módulos registram provedores de slot via provider.
- **Slot config**: ordem, visibilidade e limite por slot vivem em JSONB, editáveis no CMS.
## 2. Estrutura
```
src/layout/
├── Engine/ # motor em PHP (determinístico, testável)
│ ├── LayoutPreset.php # Enum (DIVULGACAO, DIARIO_OFICIAL, NOTICIAS, PADRAO, SCRATCH)
│ ├── PresetConfig.php # DTO readonly das regiões do preset
│ ├── SlotRegistry.php # registro/resolução determinística de provedores
│ ├── SlotProvider.php # contrato do provedor de slot
│ ├── SlotConfig.php # config (readonly) de visibilidade/ordem/limite
│ ├── ThemeResolver.php # precedeência de tema validada por schema
│ └── ThemeTokens.php # DTO readonly → CSS custom properties
├── Components/ # API pública de Blade (namespace `layout`)
│ ├── portal.blade.php # — shell público (contrato do módulo)
│ ├── cms.blade.php # — shell admin (contrato do módulo)
│ ├── slot.blade.php #
│ └── ui/icon.blade.php #
├── Portal/ # views internas do shell público (namespace `portal`)
│ ├── partials/ # skip-links, a11y-bar, header, footer, metadata
│ └── regions/ # pilhas de slot (main.left/right/header/footer)
├── Cms/ # views internas do shell admin (namespace `cms`, plano 12)
└── Assets/ # design system: css/ (tokens, base, layout, a11y, print), js/, fonts/, icons/
```
- **Grid em CSS, não em PHP:** o shell emite `data-*` (preset/regiões) e o CSS resolve o grid
(mobile-first, `fr` + `gap`); subgrid fica para **alinhamento entre componentes** (cards, forms),
com fallback `@supports`. Nada de calcular percentuais em PHP.
- **Erros:** views em `resources/views/errors/{403,404,500,503}.blade.php` (idiomático),
renderizando o shell com preset `SCRATCH`.
## 3. Contrato de slot
```php
interface SlotProvider {
public function slot(): string; // ex.: 'home.destaques'
public function order(): int; // default; sobrescrito por config (dado)
public function render(): View; // conteúdo do slot
}
```
> **Mínimo necessário (F3):** o contrato tem **só** isto. `SlotContext` / `WidgetSource` /
> `LayoutProfile` (planos 16, M3→M4) ficam **fora** do escopo de F3 — a estrutura já reserva os
> encaixes (`SlotRegistry`, ``), sem construí-los agora.
- Módulo registra no `ModuleProvider::register()`: `SlotRegistry::add(HomeDestaquesSlot::class)`.
- `SlotRegistry` resolve, respeita `SlotConfig` (visível? ordem? limite?) e renderiza.
- Config vem do `services/Theme` (JSONB), com fallback no default do provider.
- **Falha resiliente**: slot indisponível → vazio, com log estruturado (nunca 500).
## 4. Presets e grid
- `LayoutPreset` governa `showHeader`, `showFooter`, `showMainHeader`, `showMainFooter`,
`hasLeft`, `hasRight` (aprendizado do `cms/`).
- Grid mestre 21% / 55% / 21% com gap de 1.5%, via **CSS subgrid** para alinhamento.
- **Subgrid com Tailwind + daisyUI** (skill `css-moderno`): Tailwind 4 expõe
`grid-cols-subgrid`/`grid-rows-subgrid`; daisyUI não tem grid próprio (usa utilitários
Tailwind), então compõe sem conflito. Usar subgrid para **alinhamento entre componentes**
(shell sidebar/conteúdo/aside, cards com header/body/footer alinhados, formulários
label/input, tabela responsiva); para layout 1D, flexbox. Regras: o pai define as trilhas
e o filho herda (`grid-template-rows: subgrid` + `grid-row: span N`); usar **um eixo só**
quando o outro precisa de linhas próprias; **fallback**
`@supports (grid-template-rows: subgrid)` (o layout deve funcionar sem ele); preferir
subgrid a `display: contents` (a11y); manter a ordem do DOM = ordem de leitura.
- Overrides por página (`:has-left="false"`) permitidos; default = preset.
- Páginas de erro usam preset `SCRATCH` (SEO + acessibilidade sempre ativos) e
informam a URL tentada + links de recuperação (aprendizado do `cms/`).
### 4.1. Semântica, mínimo JS e PWA (ADR-010)
- Cada região renderiza **landmarks** (`header/nav/main/aside/footer`) e um único `h1`.
- Navegação, tema, filtros simples e estados usam HTML/CSS nativos; JS só onde indispensável
(editor, upload, interação com servidor).
- **PWA**: `manifest.webmanifest` + service worker de assets (registro após `load`),
servidos pelo `base-struct`; funciona como *progressive enhancement*.
- A página pública **renderiza e navega sem JS** (validado por e2e com `javaScriptEnabled: false`).
- HTML moderno: sem handlers inline (`onclick`), `rel="noopener"` em `target="_blank"`,
validação nativa de formulário e **nada** de elementos obsoletos (``, ``,
`