0} ref={containerRef}>
+
0}
+ // C101-ux — mobile-only keyboard region: the toolbar (and its native
+ // keyboard controls) is hidden on phones, so the container itself
+ // takes tabIndex and the arrow keys navigate periods. Desktop keeps
+ // the toolbar as its keyboard interface — the role/label are gated
+ // too, so the desktop a11y tree does not claim a behavior the
+ // desktop lacks.
+ tabIndex={isMobile ? 0 : undefined}
+ role={isMobile ? 'group' : undefined}
+ aria-label={isMobile ? 'Calendário de atividades — setas mudam o período' : undefined}
+ onKeyDown={handleKeyDown}
+ ref={containerRef}
+ >
{
const chrome = useMemo(
() =>
- label ? { title: label, onTitleClick: { action: onToday, hint: 'Voltar para hoje' } } : null,
+ label
+ ? {
+ title: label,
+ onTitleClick: { action: onToday, hint: 'Voltar para hoje', icon: RotateCcw },
+ }
+ : null,
[label, onToday],
)
diff --git a/src/components/campaign/activity/useAgendaKeyboardNavigation.ts b/src/components/campaign/activity/useAgendaKeyboardNavigation.ts
new file mode 100644
index 00000000..b2e9b527
--- /dev/null
+++ b/src/components/campaign/activity/useAgendaKeyboardNavigation.ts
@@ -0,0 +1,91 @@
+'use client'
+
+import { useCallback, useRef, type KeyboardEvent, type RefObject } from 'react'
+
+export type AgendaKeyboardDirection = 'next' | 'prev'
+
+const AGENDA_KEYBOARD_SKIP_SELECTOR = '[role="dialog"], [role="menu"]'
+
+/**
+ * C101-ux — pure decision for the agenda's keyboard period navigation. FullCalendar
+ * v7 has no arrow-key navigation of its own (verified in the installed bundle:
+ * only Enter/Space activation attrs and Escape in the more-popover), so the
+ * mobile agenda maps ArrowLeft/ArrowRight to prev/next on the keyboard-region
+ * container — the same direction semantics as the swipe gesture (right moves
+ * forward).
+ *
+ * Returns `null` (and the caller does nothing) when the key is not a period
+ * arrow, when a modifier is held (never hijack browser/AT shortcuts), or when
+ * the event's target lives inside a construct with its own arrow semantics:
+ * the FullCalendar more-popover (`role="dialog"`) and menus. Form controls are
+ * skipped defensively — the grid has none, but a future FC internals change
+ * must not break typing.
+ */
+export const agendaKeyboardDirection = (event: {
+ key: string
+ altKey: boolean
+ ctrlKey: boolean
+ metaKey: boolean
+ target: EventTarget | null
+}): AgendaKeyboardDirection | null => {
+ if (event.altKey || event.ctrlKey || event.metaKey) return null
+ const target = event.target
+ if (target instanceof Element) {
+ if (target.closest(AGENDA_KEYBOARD_SKIP_SELECTOR)) return null
+ if (
+ target instanceof HTMLInputElement ||
+ target instanceof HTMLTextAreaElement ||
+ target instanceof HTMLSelectElement ||
+ (target instanceof HTMLElement && target.isContentEditable)
+ ) {
+ return null
+ }
+ }
+ if (event.key === 'ArrowRight') return 'next'
+ if (event.key === 'ArrowLeft') return 'prev'
+ return null
+}
+
+/**
+ * C101-ux — keyboard period navigation for the mobile agenda. The calendar
+ * container is a keyboard region on phones (mobile-only `tabIndex={0}`,
+ * `role="group"`), so ArrowLeft/ArrowRight reach it and map to prev/next —
+ * mirroring `useAgendaSwipeNavigation`'s shape: render-gated via `enabled`
+ * (the same `isMobile` signal as the C101 chrome), and ref-based so the
+ * memoized handler always sees the current `enabled`/`onNavigate`.
+ *
+ * After navigating, focus is restored to the region: changing the period
+ * re-renders the grid and destroys the focused node (event anchor / date
+ * cell); the region survives the transition and keeps the keyboard navigating.
+ * `preventScroll` keeps the restore from scrolling the timeline.
+ */
+export const useAgendaKeyboardNavigation = ({
+ containerRef,
+ enabled,
+ onNavigate,
+}: {
+ containerRef: RefObject
+ /** Render-time gate (viewport-driven): when false, no key navigates. */
+ enabled: boolean
+ onNavigate: (direction: AgendaKeyboardDirection) => void
+}) => {
+ const enabledRef = useRef(enabled)
+ const onNavigateRef = useRef(onNavigate)
+
+ enabledRef.current = enabled
+ onNavigateRef.current = onNavigate
+
+ const handleKeyDown = useCallback(
+ (event: KeyboardEvent) => {
+ if (!enabledRef.current) return
+ const direction = agendaKeyboardDirection(event)
+ if (!direction) return
+ event.preventDefault()
+ onNavigateRef.current(direction)
+ containerRef.current?.focus({ preventScroll: true })
+ },
+ [containerRef],
+ )
+
+ return { handleKeyDown }
+}
diff --git a/src/components/campaign/shell/CampaignPageChromeText.tsx b/src/components/campaign/shell/CampaignPageChromeText.tsx
index c6e94c60..7361866d 100644
--- a/src/components/campaign/shell/CampaignPageChromeText.tsx
+++ b/src/components/campaign/shell/CampaignPageChromeText.tsx
@@ -32,9 +32,15 @@ export const CampaignPageChromeText = ({
data-slot="campaign-page-chrome-title"
title={chrome.onTitleClick.hint}
onClick={chrome.onTitleClick.action}
- className="block max-w-full truncate text-left text-sm font-semibold focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ className="flex min-w-0 max-w-full items-center gap-1.5 text-left text-sm font-semibold focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
- {chrome.title}
+ {chrome.title}
+ {chrome.onTitleClick.icon ? (
+
+ ) : null}
) : (
void; hint: string }
+ onTitleClick?: { action: () => void; hint: string; icon?: LucideIcon }
}
type CampaignRole = CampaignUser['role']
diff --git a/tests/e2e/campaignAgendaMobile.e2e.spec.ts b/tests/e2e/campaignAgendaMobile.e2e.spec.ts
index cc4a02b0..7062b141 100644
--- a/tests/e2e/campaignAgendaMobile.e2e.spec.ts
+++ b/tests/e2e/campaignAgendaMobile.e2e.spec.ts
@@ -18,12 +18,31 @@ import {
const mobileHeaderTitle = (page: Page): Locator =>
page.locator('[data-slot="campaign-mobile-top-bar"] [data-slot="campaign-page-chrome-title"]')
+/**
+ * C95 — troca a vista para Mês pelo seletor do header (menu no popover).
+ * Compartilhado pelos testes que navegam o mês com swipe ou teclado.
+ */
+const openMonthView = async (page: Page) => {
+ const viewSelector = page
+ .getByRole('button', { name: /Modo de visualização/ })
+ .filter({ visible: true })
+ await viewSelector.click()
+ await page.getByRole('menuitemradio', { name: 'Mês', exact: true }).click()
+}
+
/**
* Horizontal swipe via the CDP touch pipeline (the same input path a real
* device takes — the only way to exercise touch gestures in Playwright).
* The swipe stays at the vertical middle of the calendar, clear of fixture
- * events (which sit at 10:00), and completes far below FullCalendar's 650ms
- * long-press, so it is a navigation, not a reschedule.
+ * events (which sit at 10:00).
+ *
+ * The 5 moves are paced (~25ms apart, ~125ms total): a burst without gaps is
+ * classified by Chromium's gesture recognizer as a FLICK, and a dominant
+ * horizontal flick is a browser navigation gesture (back/forward history),
+ * not a page drag — intermittently it took the "back to today" swipe to
+ * `/campanha`. Paced, it stays a drag the agenda consumes via its
+ * non-passive touchmove preventDefault, while still finishing far below
+ * FullCalendar's 650ms long-press (which would start a reschedule).
*/
const touchSwipe = async (
cdp: CDPSession,
@@ -38,6 +57,7 @@ const touchSwipe = async (
for (let i = 1; i <= 5; i += 1) {
const x = Math.round(x0 + ((x1 - x0) * i) / 5)
await cdp.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: [{ x, y }] })
+ await new Promise((resolve) => setTimeout(resolve, 25))
}
await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] })
}
@@ -91,6 +111,10 @@ test.describe('C101 — agenda mobile com cara de app nativo', () => {
await expect(page.getByRole('button', { name: 'Dia Anterior' })).toHaveCount(0)
await expect(page.getByRole('button', { name: 'Próximo Dia' })).toHaveCount(0)
+ // C101-ux — o tap no título tem affordance visual: o glyph (aria-hidden)
+ // sinaliza o controle sem depender do tooltip hover-only.
+ await expect(mobileHeaderTitle(page).locator('svg')).toBeVisible()
+
// Navegação por arrasto: esquerda → dia seguinte; direita → volta. O
// swipe direito começa longe da borda esquerda (x=0.4): um gesto que
// nasça na borda é do Chrome (histórico), não da agenda.
@@ -124,11 +148,7 @@ test.describe('C101 — agenda mobile com cara de app nativo', () => {
// Contexto por vista: mês → nome do mês; swipe no mês → mês seguinte;
// lista → "Agenda".
- const viewSelector = page
- .getByRole('button', { name: /Modo de visualização/ })
- .filter({ visible: true })
- await viewSelector.click()
- await page.getByRole('menuitemradio', { name: 'Mês', exact: true }).click()
+ await openMonthView(page)
const monthIndex = Number(civilDate.slice(5, 7)) - 1
await expect(campaignPageChrome(page, ptBrMonthNames[monthIndex] ?? '')).toBeVisible({
timeout: 15_000,
@@ -137,6 +157,9 @@ test.describe('C101 — agenda mobile com cara de app nativo', () => {
await expect(campaignPageChrome(page, ptBrMonthNames[(monthIndex + 1) % 12] ?? '')).toBeVisible(
{ timeout: 15_000 },
)
+ const viewSelector = page
+ .getByRole('button', { name: /Modo de visualização/ })
+ .filter({ visible: true })
await viewSelector.click()
await page.getByRole('menuitemradio', { name: 'Lista', exact: true }).click()
await expect(campaignPageChrome(page, 'Agenda')).toBeVisible({ timeout: 15_000 })
@@ -268,4 +291,59 @@ test.describe('C101 — agenda mobile com cara de app nativo', () => {
expect(geometry!.stripWidth).toBe(geometry!.windowWidth)
expect(geometry!.sticky).toBe('sticky')
})
+
+ test('teclado navega períodos com ArrowLeft/ArrowRight (região focável no mobile)', async ({
+ campaign,
+ page,
+ }) => {
+ const civilDate = await seedTodayActivity(campaign, page)
+
+ await page.setViewportSize({ width: 390, height: 844 })
+ await page.goto(`${campaign.baseURL}/campanha/agenda`)
+
+ // Espera a medição mobile assentar (o label do período só existe com o
+ // chrome mobile) antes de focar a região de teclado.
+ const todayLabel = dayLabelFor(civilDate)
+ await expect(campaignPageChrome(page, todayLabel)).toBeVisible({ timeout: 15_000 })
+
+ // C101-ux — o container do calendário é a região de teclado do mobile
+ // (a toolbar — e seus controles de teclado — sumiu): focável, com label
+ // próprio, mesmo quando o período não tem eventos focáveis.
+ const region = page.locator('.activity-agenda').first()
+ await expect(region).toHaveAttribute('role', 'group')
+ await expect(region).toHaveAttribute('aria-label', /setas mudam o período/)
+ await region.focus()
+ await expect(region).toBeFocused()
+
+ // ArrowRight → período seguinte; ArrowLeft → período anterior (mesma
+ // semântica do swipe: direita avança).
+ const nextCivil = civilDatePlusDays(civilDate, 1)
+ await page.keyboard.press('ArrowRight')
+ await expect(campaignPageChrome(page, dayLabelFor(nextCivil))).toBeVisible({
+ timeout: 15_000,
+ })
+ await page.keyboard.press('ArrowLeft')
+ await expect(campaignPageChrome(page, todayLabel)).toBeVisible({ timeout: 15_000 })
+
+ // O foco permanece na região após navegar (a restauração do foco quando
+ // um nó do grid é destruído é pinada no unit do hook; aqui o contrato é
+ // que o teclado continua na região depois da troca).
+ await expect(region).toBeFocused()
+
+ // Mês: setas navegam meses conforme a vista (mesmo contrato de foco).
+ await openMonthView(page)
+ const monthIndex = Number(civilDate.slice(5, 7)) - 1
+ await expect(campaignPageChrome(page, ptBrMonthNames[monthIndex] ?? '')).toBeVisible({
+ timeout: 15_000,
+ })
+ await region.focus()
+ await page.keyboard.press('ArrowRight')
+ await expect(campaignPageChrome(page, ptBrMonthNames[(monthIndex + 1) % 12] ?? '')).toBeVisible(
+ { timeout: 15_000 },
+ )
+ await expect(region).toBeFocused()
+
+ // Setas não criam inline create (o dateClick não dispara por teclado).
+ await expect(page.getByRole('dialog')).toHaveCount(0)
+ })
})
diff --git a/tests/unit/campaignPageChromeText.unit.spec.tsx b/tests/unit/campaignPageChromeText.unit.spec.tsx
new file mode 100644
index 00000000..0dfdffd2
--- /dev/null
+++ b/tests/unit/campaignPageChromeText.unit.spec.tsx
@@ -0,0 +1,65 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { CalendarDays } from 'lucide-react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { CampaignPageChromeText } from '@/components/campaign/shell/CampaignPageChromeText'
+
+afterEach(() => {
+ cleanup()
+ vi.restoreAllMocks()
+})
+
+describe('CampaignPageChromeText (mobile)', () => {
+ it('renderiza o título como botão quando há onTitleClick', () => {
+ const action = vi.fn()
+ render(
+ ,
+ )
+ const button = screen.getByRole('button', { name: '9 Agosto' })
+ button.click()
+ expect(action).toHaveBeenCalled()
+ // Sem `icon` no contrato, o botão não renderiza glyph nenhum.
+ expect(button.querySelector('svg')).toBeNull()
+ })
+
+ it('renderiza o glyph do affordance (aria-hidden) quando onTitleClick.icon existe', () => {
+ render(
+ ,
+ )
+ const button = screen.getByRole('button', { name: '9 Agosto' })
+ const icon = button.querySelector('svg')
+ expect(icon).not.toBeNull()
+ expect(icon?.getAttribute('aria-hidden')).toBe('true')
+ })
+
+ it('não renderiza glyph sem icon no contrato', () => {
+ render()
+ expect(screen.queryByRole('button')).toBeNull()
+ expect(screen.getByText('Agenda')).toBeTruthy()
+ })
+})
+
+describe('CampaignPageChromeText (desktop)', () => {
+ it('não vira botão nem renderiza glyph — o chrome do desktop é texto', () => {
+ render(
+ ,
+ )
+ expect(screen.queryByRole('button')).toBeNull()
+ expect(screen.getByText('9 Agosto')).toBeTruthy()
+ })
+})
diff --git a/tests/unit/useAgendaKeyboardNavigation.unit.spec.tsx b/tests/unit/useAgendaKeyboardNavigation.unit.spec.tsx
new file mode 100644
index 00000000..6f9aa1d3
--- /dev/null
+++ b/tests/unit/useAgendaKeyboardNavigation.unit.spec.tsx
@@ -0,0 +1,182 @@
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { createElement, useRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+ agendaKeyboardDirection,
+ useAgendaKeyboardNavigation,
+} from '@/components/campaign/activity/useAgendaKeyboardNavigation'
+
+const keyEvent = (
+ key: string,
+ init: {
+ target?: EventTarget | null
+ altKey?: boolean
+ ctrlKey?: boolean
+ metaKey?: boolean
+ } = {},
+) => ({
+ key,
+ altKey: init.altKey ?? false,
+ ctrlKey: init.ctrlKey ?? false,
+ metaKey: init.metaKey ?? false,
+ target: init.target ?? null,
+})
+
+const Harness = ({
+ enabled = true,
+ onNavigate,
+ withChild = false,
+}: {
+ enabled?: boolean
+ onNavigate: (direction: 'next' | 'prev') => void
+ /** Simulates the grid content inside the region (date cells / event anchors). */
+ withChild?: boolean
+}) => {
+ const containerRef = useRef(null)
+ const { handleKeyDown } = useAgendaKeyboardNavigation({
+ containerRef,
+ enabled,
+ onNavigate,
+ })
+ return createElement(
+ 'div',
+ {
+ ref: containerRef,
+ tabIndex: 0,
+ onKeyDown: handleKeyDown,
+ 'data-testid': 'agenda',
+ },
+ withChild ? createElement('button', { 'data-testid': 'cell' }, 'célula') : null,
+ )
+}
+
+const pressKey = (container: HTMLElement, key: string) => {
+ const agenda = container.firstElementChild as HTMLElement
+ fireEvent.keyDown(agenda, { key })
+}
+
+afterEach(() => {
+ cleanup()
+ vi.restoreAllMocks()
+})
+
+describe('agendaKeyboardDirection', () => {
+ it('mapeia ArrowRight para o período seguinte', () => {
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight'))).toBe('next')
+ })
+
+ it('mapeia ArrowLeft para o período anterior', () => {
+ expect(agendaKeyboardDirection(keyEvent('ArrowLeft'))).toBe('prev')
+ })
+
+ it('ignora teclas que não são setas de período', () => {
+ expect(agendaKeyboardDirection(keyEvent('ArrowUp'))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowDown'))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('Home'))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('Enter'))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('a'))).toBeNull()
+ })
+
+ it('não sequestra atalhos com modificador (Alt/Ctrl/Meta)', () => {
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { altKey: true }))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { ctrlKey: true }))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { metaKey: true }))).toBeNull()
+ })
+
+ it('ignora setas dentro do more-popover do FullCalendar (role=dialog)', () => {
+ const dialog = document.createElement('div')
+ dialog.setAttribute('role', 'dialog')
+ const cell = document.createElement('button')
+ dialog.appendChild(cell)
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { target: cell }))).toBeNull()
+ })
+
+ it('ignora setas dentro de menus (o menu do seletor de vista tem setas próprias)', () => {
+ const menu = document.createElement('nav')
+ menu.setAttribute('role', 'menu')
+ const item = document.createElement('a')
+ menu.appendChild(item)
+ expect(agendaKeyboardDirection(keyEvent('ArrowLeft', { target: item }))).toBeNull()
+ })
+
+ it('ignora setas em controles de formulário (defensivo)', () => {
+ const input = document.createElement('input')
+ const textarea = document.createElement('textarea')
+ const select = document.createElement('select')
+ // jsdom não implementa isContentEditable (sempre false) — simula o
+ // elemento editável para pinar o ramo defensivo.
+ const contentEditable = document.createElement('div')
+ Object.defineProperty(contentEditable, 'isContentEditable', { value: true })
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { target: input }))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { target: textarea }))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { target: select }))).toBeNull()
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight', { target: contentEditable }))).toBeNull()
+ })
+
+ it('aceita alvos fora do DOM (target null ou não-Element)', () => {
+ expect(agendaKeyboardDirection(keyEvent('ArrowRight'))).toBe('next')
+ const text = document.createTextNode('x')
+ expect(agendaKeyboardDirection(keyEvent('ArrowLeft', { target: text }))).toBe('prev')
+ })
+})
+
+describe('useAgendaKeyboardNavigation', () => {
+ it('navega para o período seguinte com ArrowRight', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { onNavigate }))
+ pressKey(container as HTMLElement, 'ArrowRight')
+ expect(onNavigate).toHaveBeenCalledWith('next')
+ })
+
+ it('navega para o período anterior com ArrowLeft', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { onNavigate }))
+ pressKey(container as HTMLElement, 'ArrowLeft')
+ expect(onNavigate).toHaveBeenCalledWith('prev')
+ })
+
+ it('não navega com enabled=false (desktop mantém a toolbar)', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { enabled: false, onNavigate }))
+ pressKey(container as HTMLElement, 'ArrowRight')
+ pressKey(container as HTMLElement, 'ArrowLeft')
+ expect(onNavigate).not.toHaveBeenCalled()
+ })
+
+ it('bloqueia o scroll nativo da seta quando navega', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { onNavigate }))
+ const agenda = container.firstElementChild as HTMLElement
+ // fireEvent retorna o valor de dispatchEvent: false quando preventDefault
+ // foi chamado (o default da seta — scroll — é cancelado).
+ const dispatched = fireEvent.keyDown(agenda, { key: 'ArrowRight' })
+ expect(dispatched).toBe(false)
+ expect(onNavigate).toHaveBeenCalled()
+ })
+
+ it('não impede o default de teclas que não navegam', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { onNavigate }))
+ const agenda = container.firstElementChild as HTMLElement
+ const dispatched = fireEvent.keyDown(agenda, { key: 'ArrowUp' })
+ expect(dispatched).toBe(true)
+ expect(onNavigate).not.toHaveBeenCalled()
+ })
+
+ it('restaura o foco na região quando a troca de período destrói o nó focado', () => {
+ const onNavigate = vi.fn()
+ const { container } = render(createElement(Harness, { onNavigate, withChild: true }))
+ const agenda = container.firstElementChild as HTMLElement
+ const cell = agenda.querySelector('[data-testid="cell"]') as HTMLElement
+ cell.focus()
+ expect(document.activeElement).toBe(cell)
+ // A troca de período re-renderiza o grid e destrói o nó focado (âncora
+ // de evento / célula): o handler já levou o foco para a região, então a
+ // destruição do filho não derruba o teclado no body.
+ fireEvent.keyDown(cell, { key: 'ArrowRight' })
+ expect(document.activeElement).toBe(agenda)
+ cell.remove()
+ expect(document.activeElement).toBe(agenda)
+ })
+})