@devix-tecnologia/directus-extension-mapgrid 1.5.0 → 2.0.0

package/README.md

@@ -1,38 +1,628 @@
 # Directus - MapGrid Layout Extension
 
-This project is a Layout-type extension for Directus, designed for viewing content in both map and grid formats simultaneously. Developed by [Devix Tecnologia](https://devix.co).
+[![Build](https://img.shields.io/github/actions/workflow/status/devix-tecnologia/directus-extension-mapgrid/release.yml?branch=main)](https://github.com/devix-tecnologia/directus-extension-mapgrid/actions)
+[![Version](https://img.shields.io/npm/v/@devix-tecnologia/directus-extension-mapgrid)](https://www.npmjs.com/package/@devix-tecnologia/directus-extension-mapgrid)
+[![License](https://img.shields.io/npm/l/@devix-tecnologia/directus-extension-mapgrid)](https://github.com/devix-tecnologia/directus-extension-mapgrid/blob/main/License.txt)
 
-## 💎 Using the Extension
+A Layout-type extension for Directus that displays a collection in map and grid form at the same time. Built by [Devix Tecnologia](https://devix.co).
 
-- Ensure that your collection has a field of type "Map" and select the field in the Layout Options: Geolocation.
-- Enable the Layout in the settings menu on the right by selecting "MapGrid" from the dropdown.
+![Extension visualization screen](https://raw.githubusercontent.com/devix-tecnologia/directus-extension-mapgrid/develop/docs/tela.jpg)
 
-![Extension visualization screen](https://github.com/devix-tecnologia/directus-extension-mapgrid/raw/main/docs/tela.jpg)
+**🇺🇸 English** · [🇧🇷 Português](#-português)
 
-## 🚀 Running Directus with Docker Compose
+---
 
-- Download this project or copy the `docker-compose.yml` file and start a fresh installation.
-- With Docker installed on your machine ([learn more](https://docs.docker.com/get-docker/)), run the command:
+## 🇺🇸 English
 
+### Features
+
+- **Map and grid together**: the Directus map layout and the Directus table layout side by side,
+  over the same query and the same selection
+- **Click a row, the map goes there**: the map flies to the item, keeping the current zoom — or
+  zooming in, with *Zoom on focus*
+- **Click a marker, the row is marked**: instead of leaving the layout for the item page. The mark
+  is not the selection, so it does not arm the bulk actions
+- **Walk the records**: first, previous, next and last, in the query's order. When the record is on
+  another page, the page turns first
+- **Play them back**: the camera walks the records on its own, at a configurable interval. With a
+  vehicle tracking collection sorted by date, it drives the route in the order it happened
+- **Camera tracking**: *free* leaves the map where you left it, *follow* moves only when the record
+  leaves the visible area, *keep centred* keeps it in the middle at every step
+- **What the Directus layouts already do**: basemap, clustering and display template from the map
+  layout; columns, sorting, pagination and spacing from the table layout
+- **Where it is heading**: an arrow on the current record, from a course field of the data
+  (degrees from north, signed values included) or from the record visited before
+- **The trail**: the records already visited, joined in order with arrows repeated along the line,
+  the older legs fading. It joins what was visited, not the road between: a jump to a distant row
+  draws a straight leg
+- **The data's clock**: playback can wait the real time between the records, sped up (1× to 600×),
+  instead of a fixed beat. The movement is still from record to record, not continuous
+- **Timeline**: the trip on a time axis between the map and the grid, with a tick per loaded
+  record. Dragging it jumps to that moment — on any page when the query is sorted by that date
+- **Capture card**: the focused record over the map, with its photo — which enlarges on click — its
+  fields and its coordinates
+- **Measuring**: click the map to mark points and read the distance of the last leg and the total;
+  a click near a record snaps to it
+- **Reset view**: re-fit the map to the current result set at any time
+- **Bulk actions**: select rows and edit or delete them all at once from the header
+- **Guided tour**: a balloon per feature — map, grid, filters, navigation, playback, tracking,
+  direction, card, timeline, measuring and reset — from the **?** of the toolbar, or by itself on
+  the first visit of each browser
+- **Room for the map**: on Directus 10, the right sidebar starts collapsed the first time a browser
+  opens the collection; opened again, it stays as you left it. Directus 11 keeps its own choice
+- **Map and grid, resizable**: drag the handle between them to share the height (or use ↑ ↓ on
+  it); the share is kept in your preset, and a double click puts the default back
+- **Dates to the second**: the card and the timeline write moments as `27/03/2026 10:30:47`
+- **Bilingual interface**: follows the Directus app locale (en-US, pt-BR)
+
+### Installation
+
+Tested with Directus 11.17 and 10.13.
+
+```bash
+npm install @devix-tecnologia/directus-extension-mapgrid
 ```
- docker compose up
+
+### Configuration
+
+1. Make sure your collection has a field of type **Map** (geolocation).
+2. In the layout dropdown on the right, select **MapGrid**.
+3. The layout options have these sections:
+   - **Map**: the Directus map layout's own options — basemap, geospatial field, display template
+     and clustering
+   - **Grid**: the Directus table layout's own options
+   - **Zoom on focus**: zoom in on the focused record instead of keeping the current zoom. It says
+     nothing about *whether* the camera moves — that is the camera tracking's call
+   - **Playback**: how many seconds to wait between records while playing back. One second is the
+     floor, because each step asks the map for a camera animation. The pace can instead follow
+     **the data clock**, at a chosen speed, reading a date/time field — the first date of the
+     sort is used when none is chosen, and only shown, never stored
+   - **Direction**: where the current record's arrow points — nowhere, a numeric course field, or
+     the bearing from the record visited before
+   - **Trail**: how many visited records the trail joins; `0` turns it off
+   - **Capture card**: show the focused record in a card, with a photo field and the fields to list
+     (the grid's columns when none are chosen)
+   - **Tour**: open the guided tour by itself on the first visit of each browser
+
+The geospatial field is detected from the collection, so the layout works before anything is set.
+
+#### Walking the records
+
+The controls sit on the map, in the MapGrid's own toolbar:
+
+| Control | What it does |
+| --- | --- |
+| ⏮ First / ⏭ Last | The ends of the **query**, not of the page: they turn the page when they have to |
+| ◀ Previous / ▶ Next | One record. At the edge of a page, the page turns and the record is the one at the other end of it |
+| ▶ Play / ⏹ Stop | Walks forward on its own, and stops by itself at the last record |
+| GPS | Cycles the camera tracking: free → follow → keep centred |
+| 📏 Measure | Turns the ruler on: clicks on the map mark points, and **Esc** turns it off |
+| ⛶ Reset | Fits the map to the whole query again |
+| ? Tour | Opens the guided tour; **←** and **→** walk it, **Esc** closes it |
+
+The same steps answer to the keyboard while the layout has the focus: **Home** and **End** for the
+ends of the query, **←** and **→** for one record, and **Space** for play/stop. Every Directus
+shortcut carries the meta key — `meta+s`, and the `meta+a` of the table below — so holding any
+modifier hands the key back to them, and so does typing in a field. Each toolbar control shows its
+key in the tooltip.
+
+The order that defines "next" is the query's `sort`, which is the one showing in the grid header.
+Sorting by a date/time field is what makes playback drive a route in the order it happened; with
+any other sort, it walks that order instead. While a page is being fetched the controls wait, so no
+record is skipped.
+
+The current record is marked on its grid row and scrolled into view. It is deliberately **not** the
+selection: that one also arms the bulk actions, and "I am looking at this" should not read as "I
+marked this to be deleted". On the map it gets a ring of its own, drawn over the canvas: with
+**Cluster data** on, the record's point would otherwise be inside a cluster and the playback would
+be invisible. The ring is placed by projecting the geometry with the camera the map publishes,
+which it only does when a movement ends — so it appears once the camera lands.
+
+The basemaps offered are the ones in **Project Settings → Map**, as in every map of the app. The
+chosen basemap is the app's choice, not the MapGrid's: it is shared with the other map layouts and
+is not stored in the MapGrid preset — which is why a screen may look different from the one above.
+
+#### Columns
+
+Columns are chosen in the grid's own header, the way the Directus tabular layout does it — not in
+the sidebar. The **+** at the end of the header row opens the collection's field list, and dragging
+a header moves the column. Clicking a header opens that column's menu, which sorts it ascending or
+descending and hides the field — in the Directus tabular layout sorting lives in that menu rather
+than in the click itself. Every one of those choices is stored in the preset, so it is still there
+on the next visit.
+
+There is no limit on how many columns the grid can show.
+
+#### Upgrading from 1.x to 2.0
+
+2.0 composes the Directus map and table layouts instead of drawing its own, and three of the four
+options a 1.x preset stored are no longer read. Nothing is lost from the data; after upgrading, set
+these again once per collection:
+
+| 1.x option | In 2.0 |
+| --- | --- |
+| `coluna1` … `coluna5` | The grid shows the Directus default columns until they are chosen again in its header (the **+**) |
+| `geolocation` | Detected from the collection; to pick another field, use **Map → Geospatial field** in the options |
+| `title` (popup template) | **Map → Display template** in the options |
+| `zoomOnClick` | Still read, as **Zoom on focus** |
+
+### Running Directus with Docker Compose
+
+Download this project, or copy its `docker-compose.yaml`, and start a clean install. With [Docker installed](https://docs.docker.com/get-docker/), run:
+
+```bash
+docker compose up
 ```
 
-> [!IMPORTANT]
-> _The docker-compose used in this project is configured to allow iframes from any domain. In production, you should only allow trusted domains._
->
-> In the previous version, the Leaflet map was used. For it to work properly, the following CSP (Content Security Policy) settings must be configured correctly (this is no longer necessary in the current version that uses Maplibre-gl, but here's a note):
+### Read-only demo
+
+A stack to publish, where visitors try the MapGrid without changing anything. It brings the
+licence plate readings of the tests — fixed cameras, patrol cars and buses across Grande Vitória,
+with a photo each — in Portuguese, with every feature on and the tour opening on the first visit.
+
+![Demo sign-in](TASKS/assets/task-026-demo-login-depois.jpg)
 
-```yaml
-CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC: "*" # allows iframes from any domain
-CONTENT_SECURITY_POLICY_DIRECTIVES__IMG_SRC: "self http://0.0.0.0:8055 https: https://*.tile.openstreetmap.org data:" # allows map images
-DIRECTUS_HTTP_HEADERS__CONTENT_SECURITY_POLICY: "default-src *; img-src * 'self' data: https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' *; style-src 'self' 'unsafe-inline' *" # sets a global security policy for your application via the Content-Security-Policy HTTP header
+```bash
+pnpm build
+DEMO_ADMIN_PASSWORD='a strong one' pnpm demo
 ```
 
-## 📌 Important Links
+It comes up on <http://localhost:8070>; visitors sign in as `publico@example.com` /
+`senha-publica` — public on purpose, so nobody takes them for a leak — which the login page shows. The seed ends by checking, as the visitor, that reading
+works and writing is refused, and that anonymous requests are refused — a demo that turned writable
+fails there.
+
+| Variable | Default | |
+| --- | --- | --- |
+| `DEMO_ADMIN_PASSWORD` | — | Required: the demo never starts with a known admin password |
+| `DEMO_ADMIN_EMAIL` | `admin@example.com` | |
+| `DEMO_PORT` / `DEMO_PUBLIC_URL` | `8070` / `http://localhost:8070` | Set the URL to the published address |
+| `DEMO_USER_EMAIL` / `DEMO_USER_PASSWORD` | `publico@example.com` / `senha-publica` | The visitor |
+| `DEMO_KEY` / `DEMO_SECRET` / `DEMO_DB_PASSWORD` | demo values | Replace them before publishing |
+
+Publishing it:
+
+- put it behind HTTPS (a reverse proxy) and set `DEMO_PUBLIC_URL` to that address;
+- the visitors share one login, and Directus lets a signed-in user edit their own profile — the
+  password included. `pnpm demo seed` puts everything back (the visitor's password, the role, the
+  layout), so schedule it, hourly for instance;
+- the rate limiter is on, and the role reads only the readings and their photos.
+
+`pnpm demo down` stops it and keeps the data; `docker compose -f docker-compose.demo.yml down -v`
+wipes it.
+
+### Development
+
+**Prerequisites:** Node.js >= 22.13.1 and pnpm >= 10.15.0.
+
+```bash
+git clone https://github.com/devix-tecnologia/directus-extension-mapgrid.git
+cd directus-extension-mapgrid
+pnpm install
+docker compose up
+```
+
+#### Available scripts
+
+```bash
+# Development
+pnpm dev              # Build in watch mode
+pnpm storybook        # Start the Storybook dev server
+
+# Build
+pnpm build            # Build the extension
+pnpm build-storybook  # Build Storybook
+
+# Code quality
+pnpm lint             # Run the Biome linter
+pnpm lint:fix         # Fix what the linter can fix
+pnpm format           # Format the source
+pnpm typecheck        # Typecheck the source and the tests
+
+# Testing
+pnpm test             # Unit tests
+pnpm test:watch       # Unit tests in watch mode
+pnpm check:stories    # Open every story in a browser, fail on console output
+pnpm screenshot       # Regenerate docs/tela.jpg from a running Directus
+pnpm test:integration # Integration tests (requires Docker)
+pnpm test:e2e         # End-to-end tests (requires Docker)
+pnpm test:all         # Everything above that needs Docker
+
+# Stacks to try by hand (Docker)
+pnpm test:collection  # The e2e Directus with the test collections, left running (pt-BR)
+pnpm demo             # The read-only demo (needs DEMO_ADMIN_PASSWORD)
+```
+
+#### Project structure
+
+```
+src/
+├── contract/            # Shapes crossing the Directus boundary
+├── components/
+│   ├── atoms/           # DeleteAction
+│   ├── molecules/       # MapToolbar, CurrentMark, MapTrail, TripTimelineBar, CaptureCard,
+│   │                    # MeasureOverlay, TourBalloon, PaneSplitter
+│   └── templates/       # MapgridLayout, MapgridOptions
+├── services/            # One class per folder, behind an I<Name> interface
+│   ├── map-centerer/    # Moves the embedded Directus map (works around its limitation)
+│   ├── current-point/   # Projects records and coordinates onto the map pane, and back
+│   ├── embedded-layout/ # Runs a Directus layout's setup() inside the MapGrid
+│   ├── record-heading/, trail-path/, visited-path/      # direction and trail
+│   ├── playback-clock/, playback-tempo/, trip-timeline/ # playback and timeline
+│   ├── record-card/, distance-measure/, instant-format/ # card, measuring, dates
+│   ├── pane-split/      # The height shared between map and grid
+│   ├── onboarding-tour/, balloon-placement/, browser-memory/ # the tour, first visits
+│   └── optimistic-sync/ # Two writes to the preset in the same tick no longer erase each other
+├── shared/              # Extension strings (en-US, pt-BR)
+├── mocks/               # Directus environment and the mappable-collection catalogue
+└── index.ts             # Extension entry point
+```
+
+The `contract/` layer is also published as a subpath (`@devix-tecnologia/directus-extension-mapgrid/contract`), so another extension in the same project can import the same types instead of redrawing them.
+
+### Testing
+
+| Suite | Needs Docker | What it covers |
+| --- | --- | --- |
+| `pnpm test` | no | Pure logic and components, with Vitest |
+| `pnpm check:stories` | no | Every story opened in Chromium; fails on any console message |
+| `pnpm test:integration` | yes | Extension logic against a real Directus instance |
+| `pnpm test:e2e` | yes | The whole UI in a browser, with Playwright |
+
+`RUNNER_ARGS` narrows a Docker run to one spec, which is what a measurement
+usually wants: `RUNNER_ARGS=tests/e2e/mapgrid-playback-anticipation.spec.ts pnpm test:e2e`.
+
+```
+tests/
+├── stories/                      # Storybook console check (Playwright, no Docker)
+├── e2e/                          # End-to-end tests (Playwright)
+│   ├── mapgrid-layout.spec.ts    # Map/grid rendering and interaction
+│   ├── global-setup.ts           # Seeds the MapGrid preset before the suite
+│   └── helpers/map-projection.ts # Web Mercator projection for canvas clicks
+├── helpers/                      # Shared API/wait/preset helpers
+├── helper-collection.ts          # Test collection with a Map field
+├── run-docker-tests.js           # Docker runner (integration + e2e)
+└── mapgrid.spec.ts               # Integration tests (Vitest)
+```
+
+### Engineering standards
+
+Technical standard records live under [dev-docs/padroes/](dev-docs/padroes/). The codebase follows the Total TypeScript principles: honest types over assertions, derived types over duplicated shapes, and compiler and linter strictness kept on rather than silenced. Values crossing the Directus boundary are parsed in `contract/`, never asserted with `as`.
+
+### Contributing
+
+The README shows a screenshot of the running layout (`docs/tela.jpg`) right at
+the top, and it is the first thing anyone sees on GitHub and on the npm page. Any
+change that alters how a component looks has to refresh that screenshot as part
+of the same work — a stale image advertises a product that no longer exists.
+`pnpm screenshot` regenerates it against a real Directus, so this is a command
+rather than a chore. The README is two complete documents, one per language, so
+behaviour described in prose has to be corrected in both.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push the branch (`git push origin feature/amazing-feature`)
+5. Open a pull request
+
+### License
+
+MIT — see [License.txt](License.txt).
+
+### Links
+
+- [Directus documentation](https://docs.directus.io/)
+- [Directus extensions guide](https://docs.directus.io/extensions/overview.html)
+- [Report an issue](https://github.com/devix-tecnologia/directus-extension-mapgrid/issues)
+
+---
+
+## 🇧🇷 Português
+
+Extensão de layout para o Directus que exibe uma coleção simultaneamente em **mapa** e **grade**. Desenvolvida pela [Devix Tecnologia](https://devix.co).
+
+[🇺🇸 English](#-english) · **🇧🇷 Português**
+
+### Recursos
+
+- **Mapa e grade juntos**: o layout de mapa e o layout de tabela do Directus lado a lado, sobre a
+  mesma consulta e a mesma seleção
+- **Clicar na linha leva o mapa até o item**: o mapa voa até ele mantendo o zoom de agora — ou
+  aproximando, com *Zoom ao focar*
+- **Clicar no marcador marca a linha**: em vez de sair do layout para a página do item. A marca não
+  é a seleção, então não arma as ações em lote
+- **Percorrer os registros**: primeiro, anterior, próximo e último, na ordem da consulta. Se o
+  registro está em outra página, a página é trocada antes
+- **Reproduzir**: a câmera percorre os registros sozinha, num intervalo configurável. Numa coleção
+  de rastreamento veicular ordenada por data, ela refaz o trajeto na ordem em que ele aconteceu
+- **Acompanhamento da câmera**: *livre* deixa o mapa onde você deixou, *seguir* move só quando o
+  registro sai da área visível, *centralizar* mantém o registro sempre no meio
+- **O que os layouts do Directus já fazem**: mapa base, agrupamento e template de exibição vêm do
+  layout de mapa; colunas, ordenação, paginação e espaçamento vêm do layout de tabela
+- **Para onde vai**: uma seta no registro atual, a partir de um campo de rumo do dado (graus a
+  partir do norte, valores negativos inclusive) ou do registro visitado antes
+- **O rastro**: os registros já visitados, ligados em ordem, com setas repetidas ao longo da linha e
+  os trechos mais antigos esmaecendo. Liga o que foi visitado, não a rua entre eles: um salto para
+  uma linha distante desenha um trecho reto
+- **O relógio dos dados**: a reprodução pode esperar o tempo real entre os registros, acelerado (1×
+  a 600×), em vez de um intervalo fixo. O movimento continua de registro em registro, não contínuo
+- **Linha do tempo**: a viagem num eixo de tempo entre o mapa e a grade, com uma marca por registro
+  carregado. Arrastar leva àquele momento — em qualquer página quando a consulta está ordenada por
+  aquela data
+- **Card da captura**: o registro em foco sobre o mapa, com a foto — que amplia ao clicar —, os
+  campos e as coordenadas
+- **Medição**: clique no mapa para marcar pontos e ler a distância do último trecho e a total; um
+  clique perto de um registro vai até ele
+- **Reenquadrar**: reajustar o mapa ao resultado atual a qualquer momento
+- **Ações em lote**: selecionar linhas e editá-las ou excluí-las de uma vez pelo cabeçalho
+- **Apresentação guiada**: um balão por recurso — mapa, grade, filtros, navegação, reprodução,
+  acompanhamento, sentido, card, linha do tempo, medição e reenquadrar — pelo **?** da barra, ou
+  sozinha na primeira visita de cada navegador
+- **Espaço para o mapa**: no Directus 10, a barra lateral direita começa recolhida na primeira vez
+  que o navegador abre a coleção; reaberta, fica como você deixou. O Directus 11 mantém a escolha dele
+- **Mapa e grade redimensionáveis**: arraste a divisória entre eles para dividir a altura (ou use
+  ↑ ↓ nela); a divisão fica no seu preset, e um duplo clique volta ao padrão
+- **Datas até o segundo**: o card e a linha do tempo escrevem os momentos como `27/03/2026 10:30:47`
+- **Interface bilíngue**: acompanha o idioma do app do Directus (en-US, pt-BR)
+
+### Instalação
+
+Testado com o Directus 11.17 e o 10.13.
+
+```bash
+npm install @devix-tecnologia/directus-extension-mapgrid
+```
+
+### Configuração
+
+1. Garanta que a coleção possua um campo do tipo **Map** (geolocalização).
+2. No menu de layouts à direita, selecione **MapGrid**.
+3. As opções do layout têm estas seções:
+   - **Mapa**: as opções do próprio layout de mapa do Directus — mapa base, campo geoespacial,
+     template de exibição e agrupamento
+   - **Grade**: as opções do próprio layout de tabela do Directus
+   - **Zoom ao focar**: aproximar do registro focado em vez de manter o zoom de agora. Não diz nada
+     sobre *se* a câmera se move — isso é do acompanhamento da câmera
+   - **Reprodução**: quantos segundos esperar entre um registro e o próximo durante a reprodução. O
+     piso é um segundo, porque cada passo pede uma animação de câmera ao mapa. O ritmo pode, em vez
+     disso, seguir **o relógio dos dados**, numa velocidade escolhida, lendo um campo de data/hora —
+     sem escolha, vale a primeira data da ordenação, que só é mostrada, nunca gravada
+   - **Sentido**: para onde a seta do registro atual aponta — para lugar nenhum, um campo numérico
+     de rumo, ou o rumo a partir do registro visitado antes
+   - **Rastro**: quantos registros visitados o rastro liga; `0` desliga
+   - **Card da captura**: mostrar o registro em foco num card, com um campo de foto e os campos a
+     listar (as colunas da grade quando nenhum é escolhido)
+   - **Apresentação**: abrir a apresentação guiada sozinha na primeira visita de cada navegador
+
+O campo geoespacial é detectado a partir da coleção, então o layout funciona antes de qualquer
+opção ser preenchida.
+
+#### Percorrendo os registros
+
+Os controles ficam sobre o mapa, na barra do próprio MapGrid:
+
+| Controle | O que faz |
+| --- | --- |
+| ⏮ Primeiro / ⏭ Último | As pontas da **consulta**, não da página: trocam de página quando precisam |
+| ◀ Anterior / ▶ Próximo | Um registro. Na borda da página, a página vira e o registro é o da outra ponta dela |
+| ▶ Play / ⏹ Stop | Avança sozinho, e para no último registro por conta própria |
+| GPS | Cicla o acompanhamento da câmera: livre → seguir → centralizar |
+| 📏 Medir | Liga a régua: cliques no mapa marcam pontos, e **Esc** desliga |
+| ⛶ Reenquadrar | Ajusta o mapa de novo à consulta inteira |
+| ? Apresentação | Abre a apresentação guiada; **←** e **→** percorrem, **Esc** fecha |
+
+Os mesmos passos atendem ao teclado enquanto o layout está em foco: **Home** e **End** para as
+pontas da consulta, **←** e **→** para um registro, e **Espaço** para play/stop. Todo atalho do
+Directus leva a tecla meta — `meta+s`, e o `meta+a` da tabela abaixo —, então segurar qualquer
+modificador devolve a tecla para eles, e digitar num campo também. Cada controle da barra mostra a
+sua tecla na dica.
+
+A ordem que define "próximo" é o `sort` da consulta, que é o que está à vista no cabeçalho da
+grade. Ordenar por um campo de data/hora é o que faz a reprodução refazer um trajeto na ordem em
+que ele aconteceu; com qualquer outra ordem, ela percorre essa outra ordem. Enquanto uma página
+está sendo buscada, os controles esperam — nenhum registro é pulado.
+
+O registro atual é marcado na linha da grade e rolado até a vista. Ele deliberadamente **não** é a
+seleção: ela também arma as ações em lote, e "estou vendo este" não pode aparecer como "marquei
+este para apagar". No mapa ele ganha um anel próprio, desenhado sobre a tela: com o **Cluster
+data** ligado, o ponto do registro estaria dentro do agrupamento e a reprodução ficaria invisível.
+O anel é posicionado projetando a geometria com a câmera que o mapa publica, e ele só a publica
+quando um movimento termina — por isso a marca aparece quando a câmera pousa.
+
+Os mapas base oferecidos são os de **Project Settings → Map**, como em todo mapa do app. O mapa base
+escolhido é uma escolha do app, e não do MapGrid: vale também para os outros layouts de mapa e não
+fica gravado no preset do MapGrid — por isso uma tela pode parecer diferente da que está acima.
+
+#### Colunas
+
+As colunas se escolhem no próprio cabeçalho da grade, como no layout tabular do Directus — e não no
+painel lateral. O **+** no fim da linha de cabeçalho abre a lista de campos da coleção, e arrastar um
+cabeçalho move a coluna. Clicar num cabeçalho abre o menu daquela coluna, que a ordena em ordem
+crescente ou decrescente e oculta o campo — no layout tabular do Directus a ordenação mora nesse
+menu, e não no clique em si. Cada uma dessas escolhas fica gravada no preset, então continua lá na
+próxima visita.
+
+Não há limite de quantas colunas a grade exibe.
+
+#### Atualizando da 1.x para a 2.0
+
+A 2.0 compõe os layouts de mapa e de tabela do Directus em vez de desenhar os seus, e três das
+quatro opções que um preset da 1.x guardava não são mais lidas. Nada se perde dos dados; depois de
+atualizar, configure-as de novo, uma vez por coleção:
+
+| Opção da 1.x | Na 2.0 |
+| --- | --- |
+| `coluna1` … `coluna5` | A grade mostra as colunas padrão do Directus até que sejam escolhidas de novo no cabeçalho dela (o **+**) |
+| `geolocation` | Detectada a partir da coleção; para escolher outro campo, use **Mapa → Campo geoespacial** nas opções |
+| `title` (modelo do popup) | **Mapa → Template de exibição** nas opções |
+| `zoomOnClick` | Continua sendo lida, como **Zoom ao focar** |
+
+### Rodando o Directus com Docker Compose
+
+Baixe este projeto, ou copie o `docker-compose.yaml` dele, e inicie uma instalação limpa. Com o [Docker instalado](https://docs.docker.com/get-docker/), execute:
+
+```bash
+docker compose up
+```
+
+### Demonstração somente leitura
+
+Um stack para publicar, onde visitantes experimentam o MapGrid sem mudar nada. Traz as leituras de
+placas dos testes — câmeras fixas, viaturas e ônibus na Grande Vitória, cada uma com foto — em
+português, com todos os recursos ligados e a apresentação abrindo na primeira visita.
+
+![Tela de entrada](TASKS/assets/task-026-demo-login-depois.jpg)
+
+```bash
+pnpm build
+DEMO_ADMIN_PASSWORD='uma senha forte' pnpm demo
+```
+
+Sobe em <http://localhost:8070>; visitantes entram com `publico@example.com` / `senha-publica` — públicas de propósito, para
+ninguém tomá-las por vazamento —,
+que a tela de entrada mostra. A semente termina conferindo, como visitante, que ler funciona e
+escrever é recusado, e que requisições anônimas são recusadas — uma demonstração que virou
+gravável falha ali.
+
+| Variável | Padrão | |
+| --- | --- | --- |
+| `DEMO_ADMIN_PASSWORD` | — | Obrigatória: a demonstração nunca sobe com senha de admin conhecida |
+| `DEMO_ADMIN_EMAIL` | `admin@example.com` | |
+| `DEMO_PORT` / `DEMO_PUBLIC_URL` | `8070` / `http://localhost:8070` | Aponte a URL para o endereço publicado |
+| `DEMO_USER_EMAIL` / `DEMO_USER_PASSWORD` | `publico@example.com` / `senha-publica` | O visitante |
+| `DEMO_KEY` / `DEMO_SECRET` / `DEMO_DB_PASSWORD` | valores de demonstração | Troque antes de publicar |
+
+Para publicar:
+
+- coloque atrás de HTTPS (um proxy reverso) e aponte `DEMO_PUBLIC_URL` para esse endereço;
+- os visitantes dividem um login, e o Directus deixa quem está logado editar o próprio perfil —
+  senha inclusive. `pnpm demo seed` põe tudo de volta (a senha do visitante, o papel, o layout),
+  então agende-o, de hora em hora por exemplo;
+- o limitador de requisições está ligado, e o papel só lê as leituras e as fotos delas.
+
+`pnpm demo down` para e mantém os dados; `docker compose -f docker-compose.demo.yml down -v` apaga.
+
+### Desenvolvimento
+
+**Pré-requisitos:** Node.js >= 22.13.1 e pnpm >= 10.15.0.
+
+```bash
+git clone https://github.com/devix-tecnologia/directus-extension-mapgrid.git
+cd directus-extension-mapgrid
+pnpm install
+docker compose up
+```
+
+#### Scripts disponíveis
+
+```bash
+# Desenvolvimento
+pnpm dev              # Build em modo watch
+pnpm storybook        # Sobe o servidor de desenvolvimento do Storybook
+
+# Build
+pnpm build            # Compila a extensão
+pnpm build-storybook  # Compila o Storybook
+
+# Qualidade de código
+pnpm lint             # Roda o linter (Biome)
+pnpm lint:fix         # Corrige o que o linter consegue corrigir
+pnpm format           # Formata o código-fonte
+pnpm typecheck        # Checa os tipos do código e dos testes
+
+# Testes
+pnpm test             # Testes unitários
+pnpm test:watch       # Testes unitários em modo watch
+pnpm check:stories    # Abre cada story num navegador e falha se houver console
+pnpm screenshot       # Refaz docs/tela.jpg a partir de um Directus em execução
+pnpm test:integration # Testes de integração (requer Docker)
+pnpm test:e2e         # Testes ponta a ponta (requer Docker)
+pnpm test:all         # Tudo acima que precisa de Docker
+
+# Stacks para experimentar à mão (Docker)
+pnpm test:collection  # O Directus do e2e com as coleções de teste, deixado de pé (pt-BR)
+pnpm demo             # A demonstração somente leitura (pede DEMO_ADMIN_PASSWORD)
+```
+
+#### Estrutura do projeto
+
+```
+src/
+├── contract/            # Formas que cruzam a fronteira com o Directus
+├── components/
+│   ├── atoms/           # DeleteAction
+│   ├── molecules/       # MapToolbar, CurrentMark, MapTrail, TripTimelineBar, CaptureCard,
+│   │                    # MeasureOverlay, TourBalloon, PaneSplitter
+│   └── templates/       # MapgridLayout, MapgridOptions
+├── services/            # Uma classe por pasta, atrás de uma interface I<Nome>
+│   ├── map-centerer/    # Move o mapa embutido do Directus (contorna a limitação dele)
+│   ├── current-point/   # Projeta registros e coordenadas no painel do mapa, e de volta
+│   ├── embedded-layout/ # Roda o setup() de um layout do Directus dentro do MapGrid
+│   ├── record-heading/, trail-path/, visited-path/      # sentido e rastro
+│   ├── playback-clock/, playback-tempo/, trip-timeline/ # reprodução e linha do tempo
+│   ├── record-card/, distance-measure/, instant-format/ # card, medição, datas
+│   ├── pane-split/      # A altura dividida entre mapa e grade
+│   ├── onboarding-tour/, balloon-placement/, browser-memory/ # apresentação, primeiras visitas
+│   └── optimistic-sync/ # Duas escritas no preset no mesmo tick deixam de se apagar
+├── shared/              # Textos da extensão (en-US, pt-BR)
+├── mocks/               # Ambiente do Directus e catálogo de coleções mapeáveis
+└── index.ts             # Ponto de entrada da extensão
+```
+
+A camada `contract/` também é publicada como subcaminho (`@devix-tecnologia/directus-extension-mapgrid/contract`), para outra extensão do mesmo projeto importar os mesmos tipos em vez de redesenhá-los.
+
+### Testes
+
+| Suíte | Precisa de Docker | O que cobre |
+| --- | --- | --- |
+| `pnpm test` | não | Lógica pura e componentes, com Vitest |
+| `pnpm check:stories` | não | Cada story aberta no Chromium; falha a qualquer mensagem de console |
+| `pnpm test:integration` | sim | Lógica da extensão contra um Directus real |
+| `pnpm test:e2e` | sim | A interface inteira num navegador, com Playwright |
+
+O `RUNNER_ARGS` restringe uma execução no Docker a um spec só, que é o que uma
+medição costuma querer: `RUNNER_ARGS=tests/e2e/mapgrid-playback-anticipation.spec.ts pnpm test:e2e`.
+
+```
+tests/
+├── stories/                      # Checagem do console das stories (Playwright, sem Docker)
+├── e2e/                          # Testes ponta a ponta (Playwright)
+│   ├── mapgrid-layout.spec.ts    # Renderização e interação de mapa/grade
+│   ├── global-setup.ts           # Semeia o preset do MapGrid antes da suíte
+│   └── helpers/map-projection.ts # Projeção Web Mercator para cliques no canvas
+├── helpers/                      # Auxiliares de API, espera e preset
+├── helper-collection.ts          # Coleção de teste com campo Map
+├── run-docker-tests.js           # Executor Docker (integração + e2e)
+└── mapgrid.spec.ts               # Testes de integração (Vitest)
+```
+
+### Padrões de engenharia
+
+Os registros de padrão técnico ficam em [dev-docs/padroes/](dev-docs/padroes/). O código segue a filosofia Total TypeScript: tipos honestos em vez de asserções, tipos derivados em vez de formas duplicadas, e a severidade do compilador e do linter mantida ligada em vez de silenciada. Valores que cruzam a fronteira com o Directus são parseados em `contract/`, nunca asseverados com `as`.
+
+### Contribuindo
+
+O README exibe logo no topo uma captura do layout em funcionamento
+(`docs/tela.jpg`), e ela é a primeira coisa que alguém vê no GitHub e na página
+do npm. Toda mudança que altere a aparência de um componente precisa refazer essa
+captura como parte do mesmo trabalho — uma imagem desatualizada anuncia um
+produto que não existe mais. O `pnpm screenshot` refaz a imagem contra um
+Directus de verdade, então isso é um comando e não uma tarefa manual. O README
+são dois documentos completos, um por idioma, então comportamento descrito em
+texto precisa ser corrigido nos dois.
+
+1. Faça um fork do repositório
+2. Crie sua branch (`git checkout -b feature/recurso-incrivel`)
+3. Faça o commit (`git commit -m 'feat: adiciona recurso incrível'`)
+4. Envie a branch (`git push origin feature/recurso-incrivel`)
+5. Abra um pull request
+
+### Licença
+
+MIT — veja [License.txt](License.txt).
 
-- [Directus Quickstart](https://docs.directus.io/getting-started/quickstart.html) (under the Docker Installation tab)
-- [How to Create an Extension](https://docs.directus.io/extensions/creating-extensions.html)
-- [Access Directus Services](https://docs.directus.io/extensions/services/introduction.html)
-- [Access Stored Collection Items](https://docs.directus.io/extensions/services/accessing-items.html)
+### Links
 
+- [Documentação do Directus](https://docs.directus.io/)
+- [Guia de extensões do Directus](https://docs.directus.io/extensions/overview.html)
+- [Relatar um problema](https://github.com/devix-tecnologia/directus-extension-mapgrid/issues)