Planejamento da v4.0.0: padronização da API dos componentes, toolchain e limpeza

[lucasn4s]

Planejamento da v4.0.0

Galera, a ideia desta discussão é começar a fechar o escopo da v4. A #692 continua sendo o lugar para jogar ideias soltas de melhoria; aqui a proposta é organizar o que de fato entra na próxima major, principalmente o que quebra compatibilidade e por isso só cabe numa versão nova.

Como já foi dito na #692, a v4 deve ser mais incremental que a migração da v2 para a v3: nada de trocar framework, mas sim arrumar a API dos componentes, atualizar o toolchain e remover o que já está marcado como deprecated.

Abaixo vão quatro frentes, com os dados que levantamos e alguns pontos em aberto. Comentem em cada tópico: concordâncias, objeções, coisas que faltaram. As decisões que saírem daqui viram issues.

---

1. Padronizar os nomes de props e eventos

Hoje o mesmo conceito tem nomes diferentes dependendo do componente. Isso obriga quem usa o Cuida a abrir a doc de cada componente para adivinhar o nome e torna a doc mais propensa a erro. Num levantamento recente achamos páginas escutando eventos que o componente não emite justamente por isso: o DropdownButton documenta click, mas emite button-click.

Na discussão da v3 (#268) chegamos a combinar de escrever guidelines de API no CONTRIBUTING, mas isso não aconteceu. Hoje o CONTRIBUTING só diz que tudo deve estar em inglês.

1.1 Props

Alguns exemplos (entre parênteses, quantos componentes ativos usam cada nome):

Conceito	Como está hoje
Texto principal	label (20), title (19), text (10), description (4), content (Card), subtitle (3) × subTitle (AlertCard)
Tamanho	size com sm/md/lg (19; o Modal aceita também xl) × booleanos small/large (Switch), slim/thick (ProgressCircular), slim (Tooltip), compact (CalloutCard, PageHeader)
Largura	fluid (20) × block (Button) × width com presets (Select, deprecated) × fitContentWidth, verticalFluid, autoHeight
Mostrar/esconder	9 props hide*, 13 no*, 10 show* e 5 with*
Polaridade invertida	enableAutocomplete (BaseInput, SearchInput) × disableAutocomplete (TextInput)
v-model	modelValue (22) × Stepper com value + evento input (padrão do Vue 2, então v-model não funciona nele no Vue 3) × AlertCard com value sem evento
Tooltip	tooltip (inputs) × tooltipText (Button, DropdownButton, IconButton)
Erro	errorMessage (16) × errorMessageText (WebcamModal)
Ícone	icon, leadingIcon/trailingIcon, iconLeft (Chip, booleano), persistantActionIcon (com typo)
Variação visual	variant (55) convivendo com light (10), dark, dimmed, muted, ghost, secondary, prominent, theme (charts) e color (Icon, Text)

Inventário completo de props por grupo

• Texto: label: BaseInput, Checkbox, CheckboxGroup, ColorPicker, ComboBox, DateInput, DynamicInputList, FileViewer, MonthAndYearPicker, Multiselect, NumberInput, PasswordInput, Radio, … · title: AlertCard, BottomSheet, CalloutCard, Card, CollapsibleContainer, DashboardCard, Dialog, DialogModal, EmptyState, FloatingAssistant, InteractionBlockingOverlay, Modal, PageHeader, PanelCard, … · text: Alert, Button, CalloutCard, Divider, DropdownButton, EmptyState, FlatButton, Label, Link, Tooltip.
• Mostrar/esconder: hideActionButton, hideAppSwitcher, hideCustomizeButton, hideHelp, hideLabel, hideLogout, hideNotification, hideSelectAll, hideSettings · noCancelButton, noCloseButton, noCloseCancelButton, noCloseOkButton, noCloseOnBackdrop, noCloseOnEsc, noContentPadding, noFooter, noHeader, noLabel, noMargin, noTitle, noWrap · showAction, showArrows, showBackNavigation, showLabel, showLabelName, showLogout, showMenuIcon, showProfileMenu, showTarget, showText · withIcon, withOverlay, withSearch, withSearchButton, withText.
• Textos de botão: okButtonText, cancelButtonText, actionButtonText, nextButtonText, submitButtonText, savePhotoButtonText, takePhotoButtonText, takeAnotherPhotoButtonText. No SideSheet, okButtonText/cancelButtonText estão tipadas como Boolean.
• Listas: items (10), options (5), actions (3), steps (2), segments, tabs, documents, groups, avatars, fields.
• Item ativo: activeItem (5), activeStep, activeTab.

1.2 Eventos

Hoje convivem quatro estilos de nome e vários prefixos:

• kebab-case (33): button-click, item-click, tab-click, action-button-click…
• camelCase (8): boxClick (Box), cardClick (Card), cdsClick (Tile), onEnterPress, onItemClick, onRemoveRecent, onSeeMoreClick (QuickActionBar), supportLinkClick (inputs).
• Prefixos: cds- (cds-click no IconButton, cdsClick no Tile) e on/on- (on-menu-click, on-take-photo, onEnterPress…). O on gera listeners como @on-menu-click.
• v-model: update:modelValue na maioria × update:model-value (BottomSheet, WebcamModal).
• "Foi clicado" tem pelo menos 12 nomes: click, button-click, cds-click, cdsClick, boxClick, cardClick, action-click, action-clicked, item-click, navbar-click, sidebar-click, sidebar-item-click.
• Alguns componentes emitem click sem declarar em emits. O listener recebe o evento do componente e o clique nativo; no SegmentedControl cada clique dispara click duas vezes.

Inventário completo de eventos

• Uma palavra: add, cancel, change, click, close, collapse, dismiss, expand, expanded, input, logout, ok, remove, search, select, submit, subtract.
• kebab-case: action-button-click, action-click, action-clicked, button-click, cancel-action, cds-click, chart-click, click-back, click-forward, collapse-click, customize-click, disable-tip, download-click, item-click, logo-click, main-button-click, navbar-click, navigation-item-click, next-action, on-menu-click, on-take-photo, popover-item-click, profile-click, profile-menu-option-click, search-button-click, sidebar-click, sidebar-item-click, sidebar-logout, sidebar-settings, step-change, tab-click, update-fields-list, variant-chosen.
• camelCase: boxClick, cardClick, cdsClick, onEnterPress, onItemClick, onRemoveRecent, onSeeMoreClick, supportLinkClick.

1.3 Proposta

1. Escrever as guidelines de API (no CONTRIBUTING e na doc) antes de mexer em componente. Pontos para decidir juntos:
   • Texto: quando usar label (rótulo de campo/controle), title (cabeçalho de container/overlay) e text/description. O Button deveria usar label ou text?
   • Booleanos: uma polaridade só. Exemplos: hide* para esconder algo que aparece por padrão, show* para mostrar algo que não aparece. Acabar com no*, with* e pares enable*/disable* para o mesmo conceito.
   • Tamanho: depende do contexto de cada componente, e a regra precisa refletir isso.
     • Uma prop size só faz sentido quando o componente tem três ou mais tamanhos reais (sm/md/lg, e xl onde couber, como no Modal). Para um componente que só tem o padrão e uma versão reduzida, um size com sm e md vira uma prop genérica para uma escolha binária. Nesse caso, um booleano é mais honesto.
     • O que falta padronizar é o nome desse booleano. Hoje convivem small, slim e compact para ideias parecidas. Vale combinar um nome só para "versão reduzida", que pode ser o compact pedido na Discussão sobre novas melhorias e possiblidade de v4.0.0 #692 para os inputs.
     • Casos como o Switch, que tem small e large além do padrão, são três tamanhos e encaixariam em size.
     • Também é preciso separar o que é tamanho do que é outra dimensão. O slim/thick do ProgressCircular, por exemplo, fala da espessura do traço, não do tamanho do componente.
   • Largura: fluid como padrão para "ocupar toda a largura disponível". O Button usa block, que é uma convenção bem conhecida para botões (vem do Bootstrap), e não vemos problema em mantê-lo. Mas fica o ponto para discutir: mantemos block como exceção documentada no Button ou aceitamos fluid também nele, para quem usa o resto do Cuida não precisar lembrar da diferença?
   • v-model: sempre modelValue/update:modelValue.
   • Eventos: kebab-case, sem prefixo on/cds. click para o elemento principal e <elemento>-click para partes internas (item-click, action-click). Todo evento declarado em emits.
2. Travar a regra no lint: vue/custom-event-name-casing, vue/require-explicit-emits e uma checagem simples dos nomes de props no CI.
3. Migração em duas etapas:
   • Na 3.x: os nomes novos entram como alias; os antigos continuam funcionando, com warning de deprecated em dev e aviso na doc.
   • Na 4.0: os nomes antigos são removidos, com um guia de migração (tabela "antes → depois" por componente).

---

2. Toolchain e compatibilidade

Algumas atualizações de dependência que estão paradas só fazem sentido numa major:

• Node: o projeto não declara versão mínima (sem engines/.nvmrc). O CI testa 18/20/22, mas o 18 está em EOL desde abril de 2025. O vitest 5 (PR chore(deps): bump @vitest/mocker, @vitest/coverage-v8, @vitest/ui and vitest #1129) exige Node ^22.12, o que derruba 18 e 20. O publish.yml roda em 20 e o release.yml ainda em 16.
  • Proposta: declarar engines e definir o piso (≥ 20 ou ≥ 22.12?), alinhando os workflows.
• Vue: o bump do Vue para 3.5.43 (PR chore(deps): bump @vue/server-renderer and vue #1135) faz o build gerar código que depende do runtime ≥ 3.5.41. Como o Cuida não declara peerDependencies, um projeto com Vue mais antigo quebraria em silêncio.
  • Proposta: declarar peerDependencies: { vue: "^3.5.41" }. Precisamos conferir a versão do Vue nos projetos que consomem o Cuida.
• Vite 6 (PR chore(deps-dev): bump vite from 5.4.21 to 6.4.3 #1101): muda o nome do CSS gerado em lib mode, e o dist/style.css some.
  • Proposta: dá para manter o nome com build.lib.cssFileName. Decidir se a v4 aproveita para revisar os exports do pacote.
• Vitest 5 (PR chore(deps): bump @vitest/mocker, @vitest/coverage-v8, @vitest/ui and vitest #1129): depende do Vite 6 e do Node 22.

---

3. Remover o que já está deprecated

• Componentes: FilterSelect, InlineDateInput, StepperInput, Dropdown, Tabs, LoadingBar, SkeletonText, Clickable, PieChart e o util hasSlot().
  • Ponto em aberto: algum deles ainda é muito usado nos projetos? Precisa de substituto antes de sair?
• Props já anunciadas "para a v4":
  • mobile → floatingLabel (TextInput, Select, DateInput, MonthAndYearPicker, NumberInput);
  • linkText/linkUrl → supportLink/supportLinkUrl (TextInput, Select, NumberInput);
  • showTodayDot → highlightToday (DateInput);
  • allowsExpand → fluid (RadioButtonGroup);
  • width com presets (Select);
  • type="email" no TextInput → EmailInput.
• Proposta: remover tudo isso na 4.0. Na doc, os deprecated passam a ter aviso consistente na página, porque hoje alguns só têm o selo no menu lateral.

---

4. Outros temas para a v4

• Componentes ainda em Options API: cerca de 60 componentes ativos. Migrar para <script setup> não é breaking por si só, mas casa bem com a padronização de props/eventos (tipagem de props e emits) e pode ser feito junto.

• Itens que já estão na Discussão sobre novas melhorias e possiblidade de v4.0.0 #692:

  • Multiselect refeito do zero (o atual tem um erro de runtime conhecido na doc);
  • variantes "compact" dos inputs;
  • .fire no DialogModal;
  • busca com Enter nos inputs de texto;
  • automação do bump de versão;
  • estratégia de testes (Vitest × testes E2E).

• Documentação:

  • o gerador da doc não reconhece defineModel, e por isso o v-model some da doc de 19 componentes;
  • vários snippets de "Uso" foram copiados de outros componentes;
  • alguns playgrounds estão vazios.

  Não é breaking, mas vale atacar junto para a doc da v4 já sair certa. Temos um levantamento detalhado disso e vamos abrir issues separadas.

---

Como seguir

1. Comentários nesta discussão até 31/12/2026.
2. Fechamos as guidelines de API (tópico 1.3) e as decisões de Node/Vue (tópico 2).
3. As decisões viram issues com o rótulo da v4, e o desenvolvimento acontece no branch next, que já tem um workflow para publicar versões de pré-lançamento no npm, para os projetos testarem antes.
4. Na 3.x entram os aliases e warnings de deprecated; a 4.0 remove os nomes antigos e sai com o guia de migração.

Perguntas para começar:

• Para o texto principal, label ou text no Button e afins?
• Booleanos: hide*/show* resolvem todos os casos, ou precisamos de mais alguma forma?
• Tamanho: o critério "size só com 3+ tamanhos, booleano para a versão reduzida" faz sentido? Qual nome usamos para a versão reduzida (compact, small…)?
• Button: mantemos block ou aceitamos fluid também?
• Node: piso em 20 ou já em 22?
• Algum componente deprecated ainda não pode sair?
• Faltou alguma inconsistência de API que vocês já esbarraram no dia a dia?