18 KiB
Impl: Card de jingle — título completo e crédito "(feat. …)" visível (S26)
Status: aprovado (modo --auto) Atualizado em: 2026-09-21 Issue: #1240 Intenção: docs/plans/jingle-titulo-credito-artista.md Appetite restante: herdado (~0,5 dia eng; um outcome — título-base integral em até 2 linhas + crédito do artista sempre visível; sem ajuste de escopo, cortes em Rabbit holes)
Leitura da intenção
- Outcome: no card de jingle (home e
/jingles) o título-base para de truncar e o segmento final(feat. <artista>)vira uma linha própria, em corpo menor, visível parado e tocando; o dado é intocado (títulos, capas, áudio, slug, ordem, published e o nome do download) e o mesmo card serve as duas superfícies. Jingle sem(feat. …)(ex.:Axé) mantém o layout de hoje, apenas sem corte. Aria-labels seguem com o título completo. - O que NÃO negociar: extração apenas na exibição (nada de schema/migration/reedição de título); crédito nunca truncado — nem no estado tocando, nem na home, nem em
/jingles; aria-labels de play/pausa, progresso e download com o título COMPLETO; capa, botão amarelo, estado, progresso, download, filename truncado, grid, raios/sombras e o player da rádio (S25) intocados; metadata/OG de/jinglese a home cacheada (unstable_cachetagjingles) intocados; sem PII/Consent; editar o dono, sem twin. - O que reavaliar (hipóteses da "Direção no codebase"):
- Derivar no
JingleViewModelnão é o caminho barato:tests/unit/jingle.unit.spec.ts:36-51pina o objeto exato comtoEqualejinglePlayer.unit.spec.tsx:7-24/jingleHomeSection.unit.spec.tsxmontam literais typechecked — campos novos quebrariam os três sem ganho (D1). A função pura emsrc/lib/jingle.tsé a casa (módulo client-safe, dono dos derivados de exibição comojingleDownloadFilename). - O heading tem um bump
md:text-[26px](JingleCards.tsx:191) que o design derruba — ficatext-2xl(24px) em todos os viewports, comwrap-anywhereno lugar dotruncateeleading-[1.02]no lugar doleading-none(D3). - O mesmo card já é único para home (
headingLevel="h4",JingleHomeSection.tsx:81) e/jingles(JinglePlayer.tsx:11-13) — corrigir no dono cobre as duas superfícies sem branching. - Os títulos do e2e atual (
Axé oficial,Forró oficial,Pagodão oficial) não têm(feat. …), então nada quebra — mas o aceite exige cobertura e2e própria com crédito (D4).
- Derivar no
Abordagem recomendada
flowchart LR
J["collection jingle<br/>title verbatim"] --> R["jingleReads.getPublishedJingleItems()"]
R --> VM["JingleViewModel.title<br/>(completo, intocado)"]
VM --> CARD["JingleCards (dono único do card)<br/>home h4 + /jingles"]
VM --> ARIA["aria-labels play/pausa, progresso e download<br/>+ fallback de coverAlt"]
CARD --> SPLIT["splitJingleTitle<br/>(pura, src/lib/jingle.ts)"]
SPLIT --> BASE["heading: base"]
SPLIT --> CR["p.credit: 'feat. <artista>' | null"]
Opções consideradas: A) derivar no JingleViewModel | B) função pura nova em src/lib/jingle.ts chamada pelo card no render | C) parsing inline no card.
Recomendação: B — a extração é regra de exibição e mora no módulo que já é dono dos derivados de display (jingleDownloadFilename), client-safe, testável sem render, sem tocar no contrato serializado nem nos literais typechecked; jingle.title completo continua alimentando aria-labels (JingleCards.tsx:184,208,237) e o fallback de coverAlt (src/lib/jingle.ts:72).
Rejeitadas: A) quebra toEqual exato e os literais dos três specs, transforma a leitura server em contrato de apresentação e ainda exigiria carregar o título completo no VM para aria/alt (dois campos, mais churn, zero ganho); C) enterra a regra no JSX, não é unit-testável isolada e duplicaria a leitura do título para os aria-labels.
Decisões de engenharia
D1. Onde quebrar título e crédito (caro: fronteira de módulo/contrato).
- Opções: A) campos
titleBase/artistCreditnoJingleViewModel, derivados emtoJingleViewModel| B) função pura nova emsrc/lib/jingle.ts, chamada pelo card no render, shape do VM intocado | C) parsing inline no card. - Recomendação: B —
src/lib/jingle.tsé o dono existente dos derivados de exibição e é client-safe (só importa@/lib/slug); o VM (e a leiturajingleReads.ts:57-72) fica intocado, entãotests/unit/jingle.unit.spec.ts:43-50e os literais dejinglePlayer/jingleHomeSectionseguem verdes; o card continua dono único do markup nas duas superfícies. - Rejeitadas: A porque o VM viraria contrato de apresentação e quebraria os três testes pinados, além de manter dois campos para o mesmo dado; C porque não há teste possível sem render e a regra ficaria duplicada entre heading e aria-labels.
D2. Contrato e regra da função pura (caro: semântica de exibição).
- Opções: A) retorna
{ base, artist }e o card montafeat. ${artist}| B) retorna{ base, credit }comcreditpronto para exibição ('feat. É O MT'), sem parênteses | C) retorna o segmento literal'(feat. É O MT)'e o card remove os parênteses. - Recomendação: B — o unit pina exatamente a linha exibida, o card não concatena copy e o design (linha própria, sem parênteses) é atendido sem transformação no JSX. Regra: extrai apenas o segmento final, com reconhecimento case-insensitive de
feat.(rótulo normalizado parafeat., casing do artista preservado), exigindo artista e base não vazios — senão não divide; sem segmento,{ base: title, credit: null }(título verbatim, sem linha reservada). - Rejeitadas: A porque espalha a copy no JSX e o unit não pina a string final; C porque o recorte com parênteses é conflito de responsabilidade e mantém a transformação no card. Case-sensitive estrito foi considerado e rejeitado: custa zero reconhecer
(Feat. …)e o dado publicado não se reescreve; heurísticas de idioma (part.,com) e normalização de acento ficam de fora — sem sinal no dado real.
D3. Port das classes (fill-in: design é a fonte).
- Heading: remove
truncate,leading-none→leading-[1.02], ganhawrap-anywhere, removemd:text-[26px](ficatext-2xl= 24px em todos os viewports), mantémtracking-[-0.02em]e o resto. BlocoJingleCards.tsx:179:items-center→items-start. Crédito:<p>própria (mt-1.5 text-[13px] leading-[1.25] font-bold text-(--campaign-muted)) entre heading e a linha de estado.wrap-anywhere(Tailwind 4.1.18) porque o fail-safe exige quebrar palavra longa dentro do card;line-clamp-*está proibido pelo design.
D4. Estratégia de testes (custo de spec).
- Opções: A) misturar um título com
feat.nos fixtures do primeiro teste dofrontendJingles| B) teste novo focado dentro do mesmo spec serial | C) novo spec e2e (+ entrada no manifest). - Recomendação: B — o spec serial já é o dono das linhas de jingle (publica via REST,
createJingleemfrontendJingles.e2e.spec.ts:70-90) e o manifest já mapeiasrc/lib/jingleesrc/components/jinglesparafrontendJingles; o teste novo publica 1 jingle com(feat. …)e pina/jingles+ home sem reindexar asserções de contagem/índice existentes (toHaveCount(2),cardStates(['stopped','playing']), downloads). - Rejeitadas: A porque muda counts e índices já pinados e mistura escopos; C porque paga entrada nova no manifest e cria um segundo dono das linhas de jingle. Unit do card usa fixture própria (sem tocar no
JINGLEScompartilhado, para não recontargetAllByText('Pronto para tocar')).
Componentes / mudanças
splitJingleTitle(src/lib/jingle.ts, novo export puro): regex ancorada no fim/\s*\(\s*feat\.\s+([^()]+?)\s*\)\s*$/i;base = title.slice(0, match.index).trim(),artist = match[1].trim(); se match e ambos não vazios →{ base, credit: 'feat. ' + artist }; senão →{ base: title, credit: null }. Sem import novo (client-safe como o resto do módulo); retorno inferido (sem tipo exportado sem consumidor — knip).JingleCards(src/components/jingles/JingleCards.tsx, dono único do card): nomap,const { base, credit } = splitJingleTitle(jingle.title); heading (:191-193) renderiza{base}com as classes de D3;<p>de crédito logo após o heading, só quandocredit; bloco:179viraitems-start; estados:194-201, aria-labels:184/:208/:237, download:233-241e filename:242-244intocados.- Sem mudanças:
JinglePlayer.tsx,JingleHomeSection.tsx(headingLevel="h4"),jingleReads.tse a URL pública — o card compartilhado resolve as duas superfícies. - Testes:
tests/unit/jingle.unit.spec.ts(describe novo desplitJingleTitle);tests/unit/jinglePlayer.unit.spec.tsx(describe novo com fixture própria de(feat. …), parado e tocando, aria completo, semtruncate);tests/e2e/frontendJingles.e2e.spec.ts(teste novo no describe serial). docs/changelog/2026-09-21-s26.md: entrada curta de entrega.- Migration: nenhuma (nenhum schema; sem
generate:types). - Access / Consent: N/A — leitura pública, sem formulário, sem PII e sem chave de Consent.
- UI: Impeccable B — port classe-a-classe do artefato aprovado (
docs/plans/jingle-titulo-credito-artista-ui-design.html, cenas 01/02/03) sobre o card existente; crítica final do designer (tieropenai/gpt-5.6-sol).
Port do design aprovado (spec das classes)
- Título-base: Exo 2, 24px, peso 900, line-height 1.02, letter-spacing -0.02em,
overflow-wrap: anywhere; SEMtruncate; até 2 linhas nos títulos reais (o estresse passa de 2 e nada corta — crédito continua inteiro). O design mostra desktop e mobile em 24px (sem bumpmd:text-[26px]). A cena 03 usa 22px apenas como recurso de cena — não é alvo do port. - Crédito:
<p>própria sob o heading,feat. Nome do artistaSEM parênteses, 13px (mt-1.5/6px), peso 700, cor--campaign-muted(#6c615e). Nunca truncado. - Layout do bloco:
flex items-start gap-4; heading, crédito e linha de estado empilhados emmin-w-0 flex-1. Sem crédito: nenhuma linha vazia reservada. - Aria-labels preservam o título COMPLETO:
Tocar/Pausar jingle <completo>,Progresso do jingle <completo>,Baixar <completo> em MP3. - Capa, botão amarelo, estado, progresso, download, raios/sombras, grid e filename truncado: intocados.
Dados → forma (se aplicável)
N/A — a intenção declara "Vou apresentar dados? Não"; a fatia é exibição de título já publicado, sem métrica, agregação, PII ou pergunta de data-presentation.
Fases verificáveis
- Fase 1 — pura + unit (tracer, ~1 h):
splitJingleTitleemsrc/lib/jingle.ts+ describe notests/unit/jingle.unit.spec.ts(3 títulos reais —Jorge Solla 1313 (feat. Felipe Forrozeiro),(feat. Nagib Barroso),(feat. É O MT)— e bordas:Axé/Forró,(ao vivo),(feat. ), só-crédito,(FEAT. X), espaços, segmento final duplicado). Checkpoint:pnpm vitest run tests/unit/jingle.unit.spec.tsverde; nenhuma mudança visível. - Fase 2 — port do card (~1,5 h): classes/DOM em
JingleCards.tsx(D3) + describe novo emtests/unit/jinglePlayer.unit.spec.tsx(fixture própria: parado → heading base, crédito e "Pronto para tocar"; tocando → crédito permanece + "Em reprodução"; aria de play/pausa, progresso e download com título completo; sem(feat. …)→ nenhum crédito). Checkpoint:pnpm gate:fastverde e conferência visual 390/1280 contra as cenas 01/02/03. - Fase 3 — e2e (~1 h): teste novo no
frontendJingles.e2e.spec.ts(serial): 1 jingle com(feat. …),/jinglescom heading base visível, crédito visível parado e tocando, aria completo nos três controles,downloadinalterado; home (/?e2e=) com o mesmo card. Checkpoint:pnpm test:e2e -- tests/e2e/frontendJingles.e2e.spec.tsverde. - Fase 4 — fechamento (~0,5 h): crítica final do designer contra o artefato (390/1280);
pnpm gate:fast;docs/changelog/2026-09-21-s26.md; push viapnpm push(CI roda o restante). Checkpoint: PR comCloses #1240.
Rabbit holes / Não escopo (engenharia)
- Campo/relação de artista, migration e curadoria dos títulos — a intenção já corta; revisitável só com gatilho de filtrar/ordenar por artista.
- "Limpar" o
JingleViewModel/coverAlt/aria com o título-base: o título completo é contrato acessível e doalt; nada de reescrever o dado. - Qualquer
truncate/line-clamp-*como fail-safe no heading ou no crédito (o design proíbe; a cena 03 é o pin visual). - Redesenho da seção, grid (
:143), capas, player da rádio (RadioEmbed/S25), embed, metadata/OG de/jinglese otruncatedo filename (:242). - Splitter genérico para outros conteúdos (posts/tags) sem 3º call site; normalização de acento/idioma (
part.,com), parênteses aninhados e múltiplosfeat.num mesmo segmento. - Analytics/telemetria de play/download, estados novos, animação.
- Novo spec e2e ou entrada no manifest (prefixos atuais já cobrem), snapshots de DOM.
Riscos e mitigação
- Accessible name do heading muda (base no lugar do completo): deliberado pelo design; os controles seguem com o título completo — unit pina os quatro nomes e o e2e novo pina heading base; os títulos dos testes atuais não têm
(feat. …), então nada quebra. - Corte silencioso voltar: o port remove
truncatee não introduz clamp; unit do card pina a ausência detruncateno heading e a presença do crédito nos dois estados; e2e mede overflow 390 (asserção existente na home) e o visual é conferido contra as cenas. - Regex over/under-match: unit cobre os 3 títulos reais (
É O MTincluso) e as bordas; a função nunca devolve crédito vazio nem base vazia (fallback = título verbatim). - Crédito sumir no estado tocando: a
<p>fica fora do branch de estado; unit pina crédito + "Em reprodução" juntos. - Regressão nos testes pinados do VM: D1 mantém o shape; rodar a suíte unit inteira (nada de
toEqual/literais muda). - Altura/ritmo do card com título de 2 linhas:
items-startmantém o botão no topo e o bloco cresce no fluxo; cena 03 prova que nada sobrepõe/estoura; gridmd:grid-cols-3segue. - Fonte menor no desktop (26→24px): design fixa 24px; conferir a cena 01 e que nenhum seletor/teste dependa de
md:text-[26px]. - Home cacheada: mudança só de exibição; nenhuma tag/revalidação tocada; e2e da home navega com
/?e2e=. - A11y do crédito: é texto real (heading + crédito anunciados), sem
aria-hiddene sem duplicar o crédito no heading.
Aceite de engenharia
splitJingleTitlepuro emsrc/lib/jingle.ts, client-safe e sem import novo; contrato{ base, credit }com crédito pronto para exibição (feat. …) e nunca crédito vazio/base vazia.- Card único (
JingleCards) usa a função; heading semtruncate, comleading-[1.02]/wrap-anywheree semmd:text-[26px]; blocoitems-start;<p>de crédito só quando há crédito. - Aria-labels de play/pausa, progresso e download continuam com
jingle.titlecompleto; fallback decoverAltinalterado. - Nada muda em schema/migration/Consent; títulos, capas, áudio, slug, ordem, published e download filename intocados; grid, player da rádio e metadata de
/jinglesintocados. - Testes: unit puro (3 títulos reais + bordas), unit do card (parado e tocando + aria completo), e2e com
(feat. …)(crédito visível, aria completo, download inalterado) nas duas superfícies. pnpm gate:fastverde; e2e dofrontendJinglesverde; CI verde.- Changelog
docs/changelog/2026-09-21-s26.mde PR comCloses #1240.
Self-score decision-quality (gate ≥4)
| Critério | Nota | Justificativa |
|---|---|---|
| 1. Decisões caras têm rejeitadas | 5 | D1 (onde derivar: VM × pura × inline), D2 (contrato/regra do split, incl. case-sensitivity) e D4 (estratégia de teste: fixture × teste novo × spec novo) com opções, recomendação e rejeitadas justificadas; D3 é fill-in do design e está registrado. |
| 2. Abordagem cabe no appetite | 5 | ~0,5 dia: uma função pura no dono (src/lib/jingle.ts), classes/DOM no dono do card e três arquivos de teste estendidos; sem schema/migration/rota/componente/collection novo, sem novo spec e sem entrada no manifest. |
| 3. Rabbit holes nomeados | 5 | Campo/schema de artista, curadoria de títulos, clamp/truncate de fail-safe, redesign da seção/player da rádio, splitter genérico, novo spec/manifest, snapshots e telemetria explicitamente cortados. |
| 4. Depth check (reusa donos/shells) | 5 | Nenhum módulo/componente novo: a regra entra no módulo puro existente, o card segue dono único do markup (home + /jingles), a leitura/cache não muda e os testes estendem os donos; sem twin. |
| 5. Intenção (aceite) preservada | 4 | Todo o aceite mapeado; desvio visual deliberado documentado — o design derruba o bump md:text-[26px] (24px em todos os viewports) — e o crédito sem parênteses já era recomendação assumida no gate; nenhum afeta o outcome de produto. |
Média: 4,8 (≥4).