O componente Calendário é responsável pela visualização centralizada das avaliações de todas as disciplinas de um semestre. Este componente foi desenhado para oferecer uma visão global, filtrável e interativa das avaliações, integrando dados dinâmicos provenientes de ficheiros ucs.json e mantendo consistência visual com o resto da interface do utilizador.

O exemplo seguinte demonstra a utilização mínima do componente de calendário. Por omissão, este apresenta-se em modo de visualização calendar (mensal), carregando internamente os dados das disciplinas e avaliações.

<template>
  <div class="p-6">
    <Calendar />
  </div>
</template>

<script setup lang="ts">
import Calendar from '@/components/ui/calendar'
</script>

A API do componente foi desenhada para ser flexível, podes utilizar o calendário com dados internos (padrão) ou passar dados e controladores externos para integração avançada. Abaixo está a lista exaustiva de propriedades (props), eventos (emits) e métodos expostos.

Assinatura TypeScript

// Tipos principais usados pelo componente
type Avaliacao = {
  data: string; // ISO date 'YYYY-MM-DD'
  descricao: string;
  disciplina?: string;
  slug?: string;
};

type Disciplina = {
  slug: string;
  nome: string;
  avaliacoes: Avaliacao[];
};

interface CalendarConfig {
  firstWeekDay?: number; // 0 = Domingo, 1 = Segunda (padrão usado: 1)
  semesterRange?: { startMonth: number; endMonth: number }; // ex: { startMonth: 8, endMonth: 1 } para set-fev
  heatmapBucketCount?: number; // número de níveis de cor
  maxHeatmapWeeks?: number;
  dateAdapter?: 'native' | 'date-fns' | 'dayjs';
}

// Props expostas
interface CalendarProps {
  viewMode?: 'calendar' | 'list' | 'heatmap';
  disciplinasData?: Disciplina[];
  initialDate?: string | Date;
  locale?: string; // ex: 'pt-PT'
  config?: CalendarConfig;
  showLegend?: boolean;
  compact?: boolean;
  // Callbacks
  onDayClick?: (date: string, avaliacoes: Avaliacao[]) => void;
  onViewChange?: (view: 'calendar' | 'list' | 'heatmap') => void;
  onFilterChange?: (selectedSlugs: string[]) => void;
}

// Métodos expostos via ref (opcional)
interface CalendarHandle {
  goToDate: (date: string | Date) => void;
  nextMonth: () => void;
  previousMonth: () => void;
  refreshData: () => Promise<void>;
}

Props detalhadas

Eventos / Callbacks

• day-click — disparado quando o utilizador clica num dia com avaliações. Callback: (date: string, avaliacoes: Avaliacao[]) => void.
• month-change — disparado quando o mês alterou (navegação por anterior/próximo). Callback: (year: number, month: number) => void.
• filter-change — disparado sempre que as disciplinas selecionadas são alteradas. Callback: (selectedSlugs: string[]) => void.
• view-change — disparado quando o utilizador muda o modo de visualização (calendar/list/heatmap). Callback: (view: 'calendar' | 'list' | 'heatmap') => void.

Exemplo de utilização controlada (props + emits)

<template>
  <Calendar
    :viewMode="view"
    :disciplinasData="disciplinas"
    :initialDate="initialDate"
    @day-click="onDayClick"
    @filter-change="onFilterChange"
    @view-change="onViewChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import CalendarComponent from "@/components/Calendar.vue";
import disciplinas from '@/data/ucs.json'

const view = ref<'calendar'|'list'|'heatmap'>('calendar')
const initialDate = ref(new Date())

function onDayClick(date, avaliacoes) {
  // abre um modal personalizado com informações complementares
  console.log('Dia clicado', date, avaliacoes)
}

function onFilterChange(selected) {
  console.log('Disciplinas selecionadas', selected)
}

function onViewChange(v) {
  view.value = v
}
</script>

O componente principal é composto por vários subcomponentes e unidades lógicas que suportam a experiência: Painel de filtros, Vista de Calendário (grid de dias), Vista de Lista, Heatmap Semestral, Diálogo de detalhe e utilitários auxiliares. Abaixo descrevemos cada um deles, com responsabilidades, API interna e pontos de atenção.

<template>
  <div class="filters">
    <Checkbox v-model="allSelected" :indeterminate="someSelected" />
    <div class="list">
      <div v-for="d in disciplinas" :key="d.slug" class="item">
        <Checkbox :id="d.slug" v-model="selectedMap[d.slug]" />
        <label :for="d.slug">{{ d.nome }} ({{ d.avaliacoes.length }})</label>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
defineProps({
  disciplinas: Array,
  selectedMap: Object,
})
// lógica: allSelected, someSelected, watchers para emitir filter-change
</script>

// Optimização sugerida (pseudo)
const avaliacoesMap = computed(() => {
  const map = new Map()
  avaliacoes.forEach(a => {
    map.set(a.data, (map.get(a.data) || []).concat(a))
  })
  return map
})

function getAvaliacoesForDate(date) {
  const key = date.toISOString().split('T')[0]
  return avaliacoesMap.value.get(key) || []
}

// Agrupar por mês (já implementado no componente)
const agruparPorMes = (lista) => {
  const grupos = {}
  lista.forEach(a => {
    const data = new Date(a.data + 'T00:00:00')
    const mesAno = data.toLocaleDateString('pt-PT', { month: 'long', year: 'numeric' })
    if (!grupos[mesAno]) grupos[mesAno] = []
    grupos[mesAno].push(a)
  })
  return grupos
}

function getHeatmapIntensity(count: number, max: number) {
  if (count === 0) return 'bg-muted'
  const intensity = count / max
  if (intensity <= 0.25) return 'bg-chart-1/30'
  if (intensity <= 0.5) return 'bg-chart-1/50'
  if (intensity <= 0.75) return 'bg-chart-1/70'
  return 'bg-chart-1'
}

<Dialog v-model:open="dialogOpen">
  <DialogContent>
    <DialogHeader>
      <DialogTitle>{{ selectedDateFormatted }}</DialogTitle>
    </DialogHeader>
    <div v-if="avaliacoes.length">
      <div v-for="a in avaliacoes" :key="a.descricao" class="p-3 border rounded">
        <h4 class="font-semibold">{{ a.disciplina }}</h4>
        <p class="text-sm">{{ a.descricao }}</p>
        <p class="text-xs text-muted-foreground">{{ formatarData(a.data) }}</p>
      </div>
    </div>
  </DialogContent>
</Dialog>

// Exemplo: formatarData
function formatarData(dataStr: string) {
  const data = new Date(dataStr + 'T00:00:00')
  return data.toLocaleDateString('pt-PT', {
    day: '2-digit',
    month: 'long',
    year: 'numeric',
  })
}

O componente Calendário é altamente reativo. Toda a sua arquitetura interna é baseada em ref, computed e watch da Composition API. O estado principal é mínimo e derivável, permitindo uma renderização previsível e consistente, mesmo sob carga intensa (ex.: dezenas de disciplinas e centenas de avaliações).

Estrutura geral do script setup

<script setup lang="ts">
import { ref, computed, watch, onMounted } from 'vue'
import { parseISO, format, addMonths, subMonths } from 'date-fns'
import { pt } from 'date-fns/locale'

import type { Disciplina, Avaliacao, CalendarConfig } from './types'

const props = defineProps<CalendarProps>()
const emit = defineEmits(['day-click', 'month-change', 'filter-change', 'view-change'])

// Estado principal
const currentDate = ref(props.initialDate ? new Date(props.initialDate) : new Date())
const viewMode = ref(props.viewMode || 'calendar')
const selectedSlugs = ref<string[]>([])
const dialogOpen = ref(false)
const selectedDay = ref<string | null>(null)

// Computed: configuração normalizada
const config = computed<CalendarConfig>(() => ({
  firstWeekDay: props.config?.firstWeekDay ?? 1,
  semesterRange: props.config?.semesterRange ?? { startMonth: 8, endMonth: 1 },
  dateAdapter: props.config?.dateAdapter ?? 'date-fns',
  heatmapBucketCount: props.config?.heatmapBucketCount ?? 5,
  maxHeatmapWeeks: props.config?.maxHeatmapWeeks ?? 24,
}))

// Computed: disciplinas ativas
const disciplinasAtivas = computed(() => {
  if (!props.disciplinasData) return []
  if (selectedSlugs.value.length === 0) return props.disciplinasData
  return props.disciplinasData.filter((d) => selectedSlugs.value.includes(d.slug))
})

// Computed: avaliações filtradas
const avaliacoesFiltradas = computed<Avaliacao[]>(() => {
  return disciplinasAtivas.value.flatMap((d) => d.avaliacoes)
})

// Cache: mapa de avaliações por data (ISO)
const avaliacoesMap = computed(() => {
  const map = new Map<string, Avaliacao[]>()
  avaliacoesFiltradas.value.forEach((a) => {
    if (!map.has(a.data)) map.set(a.data, [])
    map.get(a.data)!.push(a)
  })
  return map
})

// Watchers
watch(viewMode, (v) => emit('view-change', v))
watch(selectedSlugs, (s) => emit('filter-change', s))

function goToNextMonth() {
  currentDate.value = addMonths(currentDate.value, 1)
  emit('month-change', currentDate.value.getFullYear(), currentDate.value.getMonth() + 1)
}

function goToPreviousMonth() {
  currentDate.value = subMonths(currentDate.value, 1)
  emit('month-change', currentDate.value.getFullYear(), currentDate.value.getMonth() + 1)
}

function onDayClick(dateStr: string) {
  const avaliacoes = avaliacoesMap.value.get(dateStr) || []
  emit('day-click', dateStr, avaliacoes)
  selectedDay.value = dateStr
  dialogOpen.value = true
}
</script>

Gestão de estado derivado

Nenhum dado é duplicado. O estado derivado é obtido dinamicamente, minimizando inconsistências:

• avaliacoesFiltradas depende de disciplinasAtivas.
• avaliacoesMap depende de avaliacoesFiltradas.
• heatmapData depende de avaliacoesMap e config.

O desenho do componente foi orientado por princípios de consistência visual, acessibilidade, desempenho e manutenção. As decisões abaixo documentam os principais trade-offs técnicos e UX considerados.

1. Consistência visual

Foi seguida a linha de design dos componentes shadcn/ui, priorizando legibilidade e hierarquia visual: cores neutras, foco claro e interacções suaves. O calendário herda as variáveis do tema definido.

2. Acessibilidade (A11Y)

• Todos os elementos interativos possuem role e aria-label.
• Navegação por teclado: setas movem o foco entre dias, Enter ativa o diálogo.
• Dialog implementado com foco cíclico e retorno automático após fecho.

3. Desempenho

• Pré-cálculo de mapas de avaliações (Map<string, Avaliacao[]>) para lookup O(1).
• Uso intensivo de computed em vez de watchers manuais.
• Lazy rendering em heatmap e lista (v-if condicional fora da viewport).

4. UX e microinterações

A navegação mensal é suave: o calendário realiza uma transição animada entre meses, evitando o salto abrupto. As células de dia são clicáveis, mas também focáveis, garantindo que o utilizador pode navegar só com teclado.

5. Modularidade

Todas as vistas (CalendarView, ListView, HeatmapView) são componentes independentes. Isto permite manter responsabilidades isoladas e facilita futuras extensões (ex.: "WeekView" ou "AgendaView").

O componente está desenhado para integrar-se diretamente com os dados definidos em ucs.json, um ficheiro que contém a estrutura de todas as unidades curriculares, incluindo avaliações, datas e metadados adicionais.

[
  {
    "slug": "matematica-i",
    "nome": "Matemática I",
    "avaliacoes": [
      { "data": "2025-09-24", "descricao": "Teste 1" },
      { "data": "2025-11-02", "descricao": "Exame final" }
    ]
  },
  {
    "slug": "fisica-i",
    "nome": "Física I",
    "avaliacoes": [
      { "data": "2025-10-13", "descricao": "Mini-teste" }
    ]
  }
]

import ucsData from '@/data/ucs.json'

function validarUCS(data: any): data is Disciplina[] {
  if (!Array.isArray(data)) return false
  return data.every((uc) => uc.slug && uc.nome && Array.isArray(uc.avaliacoes))
}

if (!validarUCS(ucsData)) {
  console.error('Estrutura de ucs.json inválida')
} else {
  console.log('Dados validados:', ucsData.length, 'disciplinas')
}

<template>
  <div class="p-6">
    <Calendar :disciplinasData="ucsData" @day-click="abrirDetalhes" />
  </div>
</template>

<script setup lang="ts">
import CalendarComponent from "@/components/Calendar.vue";
import ucsData from '@/data/ucs.json'

function abrirDetalhes(date, avaliacoes) {
  console.log('Avaliações nesse dia:', date, avaliacoes)
}
</script>

O componente foi projetado para ser reutilizável, extensível e fácil de manter. As boas práticas abaixo ajudam a garantir consistência e longevidade no projeto.

1. Tipagem e Segurança

Define sempre os tipos Disciplina, Avaliacao e CalendarConfig explicitamente. Isto evita erros silenciosos e melhora a autocompletação no editor.

2. Comunicação de Eventos

Usa defineEmits com eventos semanticamente claros. Evita enviar objetos excessivamente aninhados ou dependentes de estado interno.

3. Acessibilidade

• Evita dependências de mouse-only, testa com teclado.
• Usa labels descritivos e feedback auditivo (screen readers).
• Verifica contraste de cores e tamanhos de fonte.

4. Desempenho e Lazy Loading

Carrega apenas a vista necessária, v-if sobre o modo ativo. O heatmap e lista não devem ser montados até o utilizador os ativar.

5. Persistência e Preferências

Podes armazenar as preferências de filtro e modo de visualização no localStorage (embora para já não seja implementado nativamente):

watch(viewMode, (v) => localStorage.setItem('calendar-view', v))
onMounted(() => {
  const saved = localStorage.getItem('calendar-view')
  if (saved) viewMode.value = saved
})

7. Deploy e Internacionalização

Usa date-fns com locale configurável. Para novos idiomas, basta importar e ajustar o locale:

import { es } from 'date-fns/locale'
const config = { ...defaultConfig, locale: es }

O Calendário foi concebido como base sólida de visualização e gestão de avaliações. No entanto, existem diversas áreas de expansão já mapeadas para versões futuras, alinhadas com a evolução do ecossistema Vue e das necessidades.

1. Vistas adicionais

• WeekView: visão semanal compacta, ideal para planeamento detalhado.
• AgendaView: listagem contínua de avaliações futuras, agrupadas por disciplina.
• TimelineView: linha temporal horizontal com marcações por tipo de avaliação.

2. Sincronização externa

• Exportação para iCalendar (.ics), Google Calendar e sincronização bidirecional.
• Integração com APIs institucionais (ex.: SIGARRA, Moodle, Google Classroom).
• Webhook para notificações automáticas de alterações de datas.

3. Colaboração

Permitir que professores e estudantes adicionem anotações ou lembretes pessoais diretamente no calendário, sem afetar os dados oficiais.

4. Inteligência Adaptativa

Planeia-se a introdução de um módulo preditivo, capaz de sugerir datas de estudo ideais com base na densidade de avaliações e desempenho histórico do aluno.

5. Extensão para dispositivos móveis

• Gestos de swipe para navegar entre meses.
• Modo compacto adaptativo para ecrãs pequenos.
• Cache local e modo offline (PWA-ready).

6. Observabilidade e Telemetria

Implementação futura de métricas de uso anónimas, recolhendo eventos como mudança de vista, número médio de avaliações carregadas e frequência de acessos. Estas métricas ajudarão a priorizar otimizações reais, baseadas em uso.

7. Interoperabilidade futura

Uma das metas de médio prazo é converter o núcleo do calendário num componente web independente (<academic-calendar>), permitindo a integração com projetos não-Vue, como Astro puro, React ou Svelte.