feat(calendar): adiciona variações mês/ano e somente ano ao po-calendar e po-datepicker

[devin-ai-integration]

Summary

Adiciona duas novas variações ao po-calendar e po-datepicker:

• Mês e Ano (PoCalendarMode.MonthYear): exibe duas listas lado a lado (meses + anos) com po-button tertiary
• Somente Ano (PoCalendarMode.Year): exibe apenas a lista de anos

Principais mudanças:

• Novo enum values MonthYear e Year em PoCalendarMode
• Novo componente PoCalendarMonthYearComponent com template inline, navegação por teclado (Tab/Shift+Tab/Arrow/Enter/Space), i18n (pt/en/es/ru), e estados desabilitados via min/max date
• Novo input p-year-range (default 150) para customizar o intervalo de anos
• Integração no po-calendar (template condicional, writeValue com parsing de "MM/YYYY" e "YYYY")
• Integração no po-datepicker (passa p-mode e p-year-range, ajusta keyboard handling)
• Input manual no po-datepicker: suporte a digitação nos modos monthYear (mm/YYYY) e year (YYYY) com máscara, validação e sincronização bidirecional com o calendar
• 103+ testes unitários (novo componente + cobertura dos novos métodos no datepicker)
• CSS correspondente está na branch po-calendar/variacao-mes-ano do repo po-ui/po-style (PR #903)

Modelo de valor:

• Modo MonthYear: string "MM/YYYY" (ex: "05/2025")
• Modo Year: string "YYYY" (ex: "2025")

Updates since last revision

• Input manual para modos monthYear/Year — Novos métodos no po-datepicker:
  • Máscara de input mode-aware via buildMonthYearMask() (99/9999) e buildYearMask() (9999)
  • Getters isMonthYearMode / isYearMode no base component
  • Handlers de keyup e blur dedicados (handleMonthYearKeyup, handleYearKeyup, handleMonthYearBlur, handleYearBlur)
  • Parsing e validação de input (parseMonthYearInput — valida mês 01-12 e ano > 0)
  • Sincronização input→calendar (syncCalendarMonthYear, syncCalendarYear)
  • writeValue e formatToDate adaptados para aceitar strings nos novos modos
• Correção de formatação Prettier no po-calendar-month-year.component.ts
• Testes adicionados cobrindo todos os novos métodos no po-datepicker.component.spec.ts e po-datepicker-base.component.spec.ts

Review & Testing Checklist for Human

• formatToDate mudou de (value: Date) para (value: any) — Verificar se consumidores externos dependem da tipagem anterior. A mudança permite retornar strings para monthYear/Year, mas relaxa o type safety.
• String hardcoded 'Data inválida' como model value — Quando o input é inválido, callOnChange('Data inválida') é chamado. Isso não é internacionalizado e pode causar problemas em formulários que validam o model value. Considerar usar null ou undefined em vez de uma string de erro.
• parseMonthYearInput sempre produz modelo com separador / — O display usa o separador do locale, mas o model value sempre usa /. Verificar se isso é consistente com o formato emitido pelo calendar (MM/YYYY). A writeMonthYearValue faz split por / no model, o que pode falhar se o model vier com outro separador.
• callOnChange vs controlModel — Os modos monthYear/Year usam callOnChange diretamente (string) em vez de controlModel (Date). Isso bypassa a lógica de validação de data ISO existente. Confirmar que validators custom e reactive forms funcionam corretamente.
• Gerenciamento de foco via setTimeout — focusMonthButton, focusYearButton, focusFirstMonth, focusFirstYear, scrollToSelectedYear usam setTimeout com delays de 0/50/100ms e queries DOM diretas (querySelector). Verificar se funciona de forma confiável em diferentes velocidades de renderização.

Plano de teste sugerido:

1. Integrar CSS do po-style (branch po-calendar/variacao-mes-ano) via angular.json
2. Usar po-datepicker com [p-mode]="'monthYear'" — digitar 06/2025 no input e verificar que o calendar sincroniza mês/ano
3. Usar po-datepicker com [p-mode]="'year'" — digitar 2025 no input e verificar que o calendar sincroniza o ano
4. Testar input inválido (mês 13, ano 0000) e verificar comportamento do model
5. Selecionar mês/ano no calendar e verificar que o input atualiza corretamente
6. Testar com p-min-date, p-max-date, ngModel, e formControl (reactive forms)
7. Verificar navegação por teclado completa (Tab entre listas, Shift+Tab para fechar, Arrow keys, Enter/Space)
8. Verificar i18n trocando o idioma (pt, en, es, ru)
9. Redimensionar para < 600px e verificar layout mobile

Notes

• O componente usa standalone: false e é declarado no PoCalendarModule, consistente com os componentes existentes.
• O possível duplo tratamento de Tab no modo year (entre onYearListKeydown e onYearKeydown) do checklist anterior permanece relevante.
• O ordenamento de membros (@typescript-eslint/member-ordering) deve ser validado contra o styleguide.md do projeto.

Link to Devin session: https://totvs.devinenterprise.com/sessions/d76cc54521ea46379983423f76b7cea5

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring