# TimelineItem

> Componentes / Conteúdo · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Um marco de linha do tempo: ano, marcador e linha que liga ao próximo, título e descrição. O marco atual ganha marcador cheio e "momento atual" para quem ouve. No celular, o ano sobe para cima do título.

- Função: Conteúdo
- Também chamado de: linha do tempo, marco, histórico, timeline
- Mora em: `app/components/molecules/TimelineItem.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/TimelineItem](https://phorte-design-system.vercel.app/styleguide/peca/TimelineItem)
- Ficha no Storybook: [components-complex-timelineitem](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-timelineitem--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/TimelineItem/0](https://phorte-design-system.vercel.app/previa/TimelineItem/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { TimelineItem } from '@/app/components/molecules/TimelineItem';

<TimelineItem year={…} title={…} description={…}>…</TimelineItem>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Linha completa](https://phorte-design-system.vercel.app/previa/TimelineItem/0)
2. [Padrão](https://phorte-design-system.vercel.app/previa/TimelineItem/1)
3. [Atual](https://phorte-design-system.vercel.app/previa/TimelineItem/2)
4. [Texto longo](https://phorte-design-system.vercel.app/previa/TimelineItem/3)
5. [Pelo contêiner Timeline](https://phorte-design-system.vercel.app/previa/TimelineItem/4)

Em sequência, para contar uma história em datas — a trajetória da instituição, as etapas de um processo seletivo.

### Quando não usar

Para as próximas turmas com datas e vagas, use o TurmaCard. Para passos numerados sem data, uma lista ordenada.

### Faça

- Monte a linha pelo contêiner `Timeline` (E72): ele faz a `<ol>` com cada item como `<li>`, tira a linha do último e marca o `atual` pelo índice ou pelo ano.
- Avulso, use `as="li"` dentro de uma `<ol>` e marque `isLast` no último — é o que o `Timeline` faz sozinho.
- Use `atual` em um marco só.
- Acerte o nível do título com `tituloComo` (`h3` por padrão).

### Evite

- Marcos sem ordem cronológica.
- Mais de um `atual`.

### Anatomia

1. **Ano** — À esquerda no computador (24px, `font-black`, vermelho); acima do título no celular.
2. **Trilho** — Marcador redondo de 14px e a linha até o próximo — decorativos.
3. **Título** — `h3` por padrão, `text-lg` em negrito.
4. **Descrição** — Texto cinza, até a largura de leitura.

### Estados

| Estado | O que muda |
| --- | --- |
| Padrão | Marcador vazio (fundo `--card`) com borda vermelha. |
| Atual | `atual`: marcador cheio com contorno afastado, "— momento atual" escondido no título e `data-atual`. |
| Último | `isLast`: sem a linha e sem o espaço de baixo. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Abaixo de 768px | O ano da coluna esquerda some e aparece acima do título — um só é exibido por vez. |

### Relacionados

- [TurmaCard](https://phorte-design-system.vercel.app/styleguide/md/TurmaCard.md) — Turmas com data e vagas.
- [EventSchedule](https://phorte-design-system.vercel.app/styleguide/md/EventSchedule.md) — Programação de um evento, por horário.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `year` | `string` | — | sim |  |
| `title` | `string` | — | sim |  |
| `description` | `React.ReactNode` | — | sim |  |
| `isLast` | `boolean` | `false` | não | O último item não desenha a linha para baixo. |
| `atual` | `boolean` | `false` | não | O momento presente da linha do tempo. |
| `as` | `ElementType` | `'div'` | não | Elemento raiz. Use `li` dentro de uma `<ol>`. |
| `tituloComo` | `ElementType` | `'h3'` | não | Nível do título. Padrão `h3`; acerte conforme a página. |

Aceita também: `Omit<React.HTMLAttributes<HTMLElement>, 'title'>`.

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Marcador | 14px | `size-3.5` |
| Coluna do ano | 112px a partir de 768px | `md:grid-cols-[7rem_1.5rem_1fr]` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--primary` | #D42B2B | `bg-primary`, `border-primary`, `outline-primary`, `text-primary` |
| `--border` | #E5E5E5 | `bg-border` |
| `--card` | #FFFFFF | `bg-card` |
| `--foreground` | #1A1A1A | `text-ink` |
| `--muted-foreground` | #595959 | `text-muted-foreground` |

## Acessibilidade

### Leitor de tela

- O ano vem num `<time>` (E72): com quatro dígitos, o `dateTime` leva o ano, e a data fica legível por máquina.
- Pelo `Timeline`, a linha é uma lista ordenada com `li` — sem o contêiner, esquecer `as="li"` dava `div` dentro de `ol`, que o axe acusa (conferido no teste da ficha).
- O trilho é `aria-hidden`: ano e título estão em texto.
- O marco atual diz "momento atual" no título, e não só pelo marcador cheio.

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/TimelineItem.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-timelineitem--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/TimelineItem.tsx