docs(agents): encode list-export convention as GR-UI-EXPORT guard
Make the core-primitive-end-to-end rule for Grid.js list exports binding instead of advisory — so future consumers (and reviewers) cannot quietly drift back into inline fputcsv / hand-rolled headers / bespoke click listeners / lurl() for query-carrying URLs. - CLAUDE.md: new UI Patterns bullet + two "Never Do This" entries spelling out the server/view/client contract in one place. - .agents/checks/guard-catalog.json: new GR-UI-EXPORT entry describing the end-to-end requirement (exportRequireGetRequest + exportCapLimit + exportSendCsv + ExportColumn + shared filter-schema + dropdown partial + endpointUrl() + initListExport). - .agents/checks/guard-enforcement-map.json: wire the new guard to tests/Architecture/ListExportContractTest.php as the automated evidence source. - .agents/checks/guard-checklist.md & .agents/prompts/reviewer-code.md: add GR-UI-EXPORT so the Code Reviewer prompt and the checklist flag violations alongside GR-UI-LIST. - tests/Architecture/ListExportContractFiles: registry of every list export (currently helpdesk-domains, admin/users, audit/system-audit). Adding a new list = one entry, contract test covers the rest. - tests/Architecture/ListExportContractTest: six checks per registered entry — endpoint uses the primitive, no hand-rolled output, data and export share the same filter-schema, template includes the dropdown partial and uses endpointUrl(), page module imports and invokes initListExport, and the shared dropdown partial stays zero-config. - pages/admin/users/export().php: align with the new contract by switching from ad-hoc requestInput()->queryAll() reads to gridParseFiltersFromSchemaFile(__DIR__ . '/filter-schema.php'), same as the data endpoint — eliminates the last place Grid and export could disagree on what "the current filter" means. Gates: PHPUnit 1900 OK (+6 contract checks), PHPStan 0 errors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -171,6 +171,10 @@ docker/ # Dockerfiles, Nginx configs, PHP configs
|
||||
- **Components inside forms**: Reset core `margin-bottom` on buttons/inputs/selects/labels at component scope. Checkboxes in flex need explicit `1.25em` sizing + `flex-shrink: 0`.
|
||||
- **Sticky elements**: Always use `top: calc(var(--app-topbar-height) + ...)` — never `top: 0`. Multi-column grids must have a responsive single-column `@media` fallback.
|
||||
- **File uploads** use `app-file-upload.phtml` partial (deliberate exception to plain-HTML inputs — the markup is too complex for inline use). See `templates/partials/app-file-upload.phtml` for the `$fileUpload` array contract. Never write file-upload markup inline; always use the partial.
|
||||
- **List exports**: every Grid.js list that offers a download MUST go through the core primitive — no inline `fputcsv`, no hand-rolled headers, no bespoke dropdown. (GR-UI-EXPORT)
|
||||
- **Server:** endpoint calls `exportRequireGetRequest()` + `exportCapLimit()` + `exportSendCsv()` from `core/Support/helpers/export.php`, builds columns as `ExportColumn[]` (`core/Service/Export/CsvExportService.php`), and reuses the SAME `filter-schema.php` via `gridParseFiltersFromSchemaFile()` as the data endpoint. Extract a shared service or presenter if row-formatting is non-trivial (see `DomainListService` / `SystemAuditRowPresenter`).
|
||||
- **View:** `require templatePath('partials/app-list-export-dropdown.phtml');` inside `$listTitleActionsHtml`. Pass the URL via `'exportUrl' => endpointUrl('<route-path>')` in the page config — **always `endpointUrl()`, never plain `lurl()`**. The helper resolves module routes to their target path so query strings survive.
|
||||
- **Client:** `initListExport({ gridConfig, exportUrl })` from `/js/core/app-list-export.js`. No hand-rolled click listener, no inline URL construction.
|
||||
|
||||
### Never Do This
|
||||
|
||||
@@ -186,6 +190,8 @@ docker/ # Dockerfiles, Nginx configs, PHP configs
|
||||
- Inline SQL or string-concatenated queries (GR-SEC-003)
|
||||
- Raw `echo` in views without `// raw-html-ok` marker — use `e()` (GR-SEC-010)
|
||||
- OpenAPI changes without updating the spec (GR-CORE-007)
|
||||
- Hand-rolled list exports (inline `fputcsv`, own header setup, bespoke click-to-download JS) — always use `core/Service/Export/*` + `exportSendCsv()` + `app-list-export-dropdown.phtml` + `initListExport()` (GR-UI-EXPORT)
|
||||
- Building an export/data endpoint URL with `lurl()` when it will carry query params — use `endpointUrl()` so module routes where `path ≠ target` still resolve (GR-UI-EXPORT)
|
||||
|
||||
## Database
|
||||
|
||||
|
||||
Reference in New Issue
Block a user