Timeline Devix - Extensão de Layout para Directus

A Timeline Devix é uma extensão de layout personalizada para o Directus, projetada para exibir itens de uma coleção em formato de timeline vertical. Cada item é representado como um evento com data, status/criticidade + 5 campos de exibição personalizada, agrupado por dia com headers visuais (ex: "Dia 01/09/2025"). A extensão é ideal para visualizar eventos cronológicos, como logs, atividades ou históricos diversos.

📑 Conteúdo

• Funcionalidades
• Pré-requisitos
• Instalação
• Configuração no Directus
• Desenvolvimento
• Testes Automatizados
• CI/CD e Release
• Solução de Problemas
• Contribuindo
• Licença

Funcionalidades

• Visualização de Timeline: Exibe itens em uma linha do tempo vertical com uma linha central visível, adaptada ao tema do Directus (claro/escuro).
• Agrupamento por Dia: Itens são agrupados por data (ex: "Dia 01/09/2025"), com headers visuais indicando o dia.
• Campos Personalizáveis:
  • Data (data): Formatada como DD/MM/YYYY HH:mm (fuso America/Sao_Paulo).
  • Criticidade/Status (criticidade): Indicada por cores no marcador de acordo com estrutura de campo de seleção no Directus.
  • campoUm, campoDois, campoTres, campoQuatro e campoCinco: campos personalizáveis podendo exibir informações de campos diversos.
• Interatividade: Cada evento é clicável, levando à tela de edição do item no Directus (/content/{collection}/{itemId}).
• Ordenação: Itens ordenados por data (descendente, mais recentes primeiro).
• Paginação: Suporta navegação por páginas e seleção de itens por página (5, 10, 25, 50, 100, etc.).
• Estilo Moderno: Design responsivo com sombras suaves, transições ao hover e adaptação ao tema do Directus.

Pré-requisitos

• Directus: Versão 9.x ou superior.
• Node.js: Versão 16.x ou superior.
• pnpm: Gerenciador de pacotes para build.
• Coleção no Directus: Deve conter campos para id, data, criticidade, title, description e campoCinco (os nomes podem ser configurados).

Instalação

Via npm (Recomendado)

A forma mais fácil de instalar a extensão é através do npm:

# No diretório do seu projeto Directus
npm install @devix-tecnologia/directus-extension-timeline-devix

# ou com pnpm
pnpm add @devix-tecnologia/directus-extension-timeline-devix

# ou com yarn
yarn add @devix-tecnologia/directus-extension-timeline-devix

Após a instalação, reinicie o Directus e a extensão estará disponível na lista de layouts.

Instalação Manual (Desenvolvimento)

1. Clone ou copie o projeto:

   git clone https://github.com/devix-tecnologia/timeline-devix-directus.git
   cd timeline-devix-directus

2. Instale as dependências:

   pnpm install

3. Compile a extensão:

   pnpm run build

4. Copie para o Directus: Copie o diretório dist para a pasta de extensões do Directus:

   cp -r dist /caminho/para/directus/extensions/timeline-devix

5. Reinicie o Directus: Reinicie o servidor do Directus para carregar a extensão.

Configuração no Directus

1. Acesse o Directus: Faça login no painel de administração.

2. Configure a coleção:

   • Crie ou use uma coleção com campos para:
     • id (chave primária).
     • data (formato ISO, ex: 2025-09-24T17:07:00Z).
     • campoUm (texto).
     • criticidade (texto, ex: "Alto", "Médio", "Baixo").
     • title (texto).
     • description (texto).
     • campoCinco (texto).
   • Certifique-se de que os campos têm permissões de leitura para o usuário.

3. Adicione o layout:

   • Na visualização de dados de uma coleção, selecione o layout "Timeline Devix".
   • No painel de opções do layout, selecione os campos correspondentes para:
     • Data/hora
     • Criticidade
     • Mais 5 campos de acordo com necessidade

4. Teste a timeline:

   • Verifique se os itens aparecem ordenados por data, agrupados por dia.
   • Confirme que os marcadores refletem a criticidade (vermelho, amarelo, verde).
   • Clique em um evento para abrir a tela de edição.
   • Navegue pelas páginas usando a paginação.

Estrutura do Projeto

timeline-devix/
├── src/
│   ├── actions.vue     # Componente para ações (ex: botões no topo)
│   ├── index.ts        # Lógica principal do layout (agrupamento, queries)
│   ├── layout.vue      # Componente de visualização da timeline
│   ├── options.vue     # Componente para configuração de campos
│   ├── types.ts        # Definições de campoCincos (LayoutOptions, LayoutQuery)
├── package.json        # Dependências e scripts
├── README.md           # Documentação (este arquivo)
├── dist/               # Build gerado

Dependências

• @directus/extensions-sdk: SDK para criar extensões no Directus.
• vue: Framework para componentes reativos.
• vue-i18n: Internacionalização.
• vue-router: Navegação para edição de itens.
• Sem dependências externas adicionais (formatação de data usa toLocaleString).

Desenvolvimento

Para desenvolver ou modificar a extensão:

1. Modo de desenvolvimento local:

   pnpm dev

2. Executar com Docker Compose:

   docker compose up

   Acesse o Directus em: http://localhost:8055

   • Usuário admin será criado automaticamente conforme docker-compose.yaml

3. Executar testes:

   # Testes unitários
   pnpm test
      
   # Testes de integração
   pnpm test:integration
      
   # Testes em modo watch
   pnpm test:watch

4. Estrutura dos componentes:

   • index.ts: Define o layout, gerencia queries e agrupa itens por dia.
   • layout.vue: Renderiza a timeline com headers de dia, eventos clicáveis e paginação.
   • options.vue: Interface para selecionar campos da coleção.
   • actions.vue: (Opcional) Botões de ação no topo.
   • types.ts: Definições TypeScript para opções e queries.

5. Estilização:

   • Usa variáveis CSS do Directus (--background-page, --background-inverted, etc.) para adaptação ao tema.
   • Linha central com z-index: 2 para sobreposição aos cards.
   • Efeitos de hover e transições para interatividade.

Testes Automatizados

Este projeto implementa uma infraestrutura avançada de testes automatizados, testando contra múltiplas versões do Directus automaticamente.

📚 Leia a documentação completa de testes

Características

• ✅ Testes contra múltiplas versões do Directus (11.0+)
• ✅ Atualização automática de versões testadas (diariamente)
• ✅ CI/CD com GitHub Actions
• ✅ Release automático com semantic-release
• ✅ Docker Compose para ambiente isolado de testes

Quick Start

# Instalar dependências
pnpm install

# Executar testes de integração
pnpm test:integration

# Executar contra uma versão específica
DIRECTUS_VERSION=11.5.1 pnpm test:integration

CI/CD e Release

O projeto usa semantic-release para releases automáticos:

# Commits seguem convenção semântica
git commit -m "fix: corrige bug no filtro"     # Patch: 1.0.0 -> 1.0.1
git commit -m "feat: adiciona novo campo"      # Minor: 1.0.0 -> 1.1.0
git commit -m "feat!: remove Directus 10"      # Major: 1.0.0 -> 2.0.0

Cada push na branch main/master dispara:

1. Lint e validação
2. Testes contra múltiplas versões
3. Build da extensão
4. Release automático no GitHub

Solução de Problemas

• Itens não aparecem:
  • Verifique se os campos da coleção estão mapeados corretamente no painel de opções.
  • Confirme permissões de leitura na coleção.
• Erro de navegação:
  • Abra o DevTools (F12) e procure por erros como "Cannot read property 'push' of undefined".
  • Certifique-se de que a coleção tem um campo de chave primária (id).
• Datas não formatadas:
  • Confirme que o campo data está em formato ISO ou compatível com new Date().
• Estilo desalinhado:
  • Verifique se o Directus está usando um tema personalizado que sobrescreve as variáveis CSS.

🤝 Contribuindo

Contribuições são muito bem-vindas! Veja nosso guia de contribuição para começar.

• Reporte bugs abrindo uma issue
• Sugira novas funcionalidades
• Envie Pull Requests
• Melhore a documentação

📄 Licença

Este projeto está licenciado sob a MIT License.

🏢 Sobre

Desenvolvido e mantido por Devix Tecnologia

⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!

📞 Suporte

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussões: GitHub Discussions