{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "timeline", "title": "Timeline", "author": "Visant Labs ", "description": "Linha do tempo com progresso amarrado ao scroll.", "dependencies": [ "framer-motion" ], "registryDependencies": [ "utils" ], "files": [ { "path": "registry/visant/ui/timeline.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n motion,\n useMotionValueEvent,\n useReducedMotion,\n useScroll,\n useTransform,\n} from \"framer-motion\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * Timeline — a linha do tempo que avança junto com a página.\n *\n * ── O que estava errado aqui, e não era \"estilo\" ───────────────────────────\n *\n * Esta peça entrou no registry colada de fora e ninguém passou a régua:\n *\n * · **Copy de outra marca dentro do item.** O componente escrevia, fixo no\n * corpo, \"Changelog from my journey\" e \"I've been working on Aceternity for\n * the past 2 years\". Quem instalasse recebia o texto de outra pessoa e teria\n * que editar o arquivo do registry pra tirar. Agora a cabeça é slot: sem\n * `title` a linha começa direto no primeiro nó, que é o piso honesto.\n * · **Cor crua de paleta.** `bg-white`, `dark:bg-neutral-950`, `text-black`,\n * `from-purple-500 via-blue-500`. Roxo e azul não são de marca nenhuma —\n * eram de todas. Agora o trilho é `--border` e o preenchido é `--brand`, então\n * a mesma linha sai na cor de quem instalou.\n * · **Animar `height`.** O preenchimento crescia por altura, que é layout a cada\n * quadro. Virou `scaleY` com origem no topo: mesma leitura, no compositor.\n * · **Nó sem estado.** Os doze pontos eram idênticos do começo ao fim, então a\n * linha não dizia onde a pessoa está. Agora cada nó tem três estados — feito,\n * agora, a seguir — e eles saem da MESMA fração que preenche o trilho, medida\n * uma vez por layout. Sem isso o ponto e o traço discordariam na tela.\n * · **`py-20 md:px-10 max-w-7xl` embutido.** A peça impunha a largura e o\n * respiro da página inteira, então ela só cabia numa página inteira. Dentro de\n * um painel, de uma coluna ou de um card, saía cortada. Agora o item ocupa o\n * que o pai der.\n *\n * ── A anatomia ────────────────────────────────────────────────────────────\n *\n * `rótulo (meta) → título → corpo`, com o nó do trilho ao lado servindo de\n * evidência. Sem `meta`, o rótulo vira \"Etapa 01\" — numerar é melhor que deixar\n * o degrau sem nome, porque é o número que deixa a pessoa dizer \"travei na 3\".\n *\n * Quem pediu menos movimento recebe a linha inteira preenchida e todos os nós\n * no estado final: o conteúdo é o mesmo, sem percurso.\n *\n * ── Quem rola ─────────────────────────────────────────────────────────────\n *\n * Por padrão, a página. Com `scrollContainer`, um contêiner próprio: a linha\n * mora num painel, num modal ou num card com rolagem, e o progresso passa a ser o\n * percurso DELE. Sem isso a peça ficava muda em qualquer lugar onde a página não\n * rola, presa no estado em que nasceu.\n *\n * ── Por que o estado deixou de ser uma palavra ────────────────────────────\n *\n * Antes, o degrau atual se anunciava com a etiqueta \"agora\" ao lado da data:\n * caixa alta, mono, tracking largo — a terceira etiqueta em caixa alta da mesma\n * linha, contando com a data e com o que o consumidor põe no corpo. É esse\n * empilhamento de etiqueta que dá a cara de gerado por IA: tudo vira rótulo e\n * nada vira desenho. E era etiqueta redundante, porque o nó ao lado já estava\n * dizendo a mesma coisa.\n *\n * O estado agora é ANATOMIA, não texto:\n *\n * · **feito** — nó cheio, conteúdo em peso normal. Já passou, não pede atenção.\n * · **agora** — o marco ganha superfície: cartão com fundo, borda e um fio da\n * marca colado na esquerda, encostando no trilho. É o único degrau com caixa\n * na coluna inteira, então o olho acha em um quadro, sem ler nada.\n * · **a seguir** — nó vazado e título em cinza de apoio. Está lá, ainda não é\n * agora. O recuo NÃO é por opacidade: opacidade em cima de `--muted-foreground`\n * derruba o contraste do texto abaixo do piso de legibilidade, e o degrau que\n * ainda não chegou é justamente o que a pessoa está tentando ler.\n *\n * A palavra continua existindo pra quem não vê a tela, em `sr-only`: leitor de\n * tela não enxerga fio nem fundo, e \"onde eu estou\" é a pergunta que a peça\n * existe pra responder. Texto invisível não é etiqueta — é a legenda do desenho.\n */\n\nexport interface TimelineEntry {\n title: React.ReactNode;\n content: React.ReactNode;\n /** O rótulo acima do título: data, fase, prazo. Sem isto vira \"Etapa 01\". */\n meta?: React.ReactNode;\n}\n\nexport interface TimelineProps\n extends Omit, \"title\"> {\n data: TimelineEntry[];\n /** Cabeça opcional. Sem ela a linha começa direto no primeiro nó. */\n title?: React.ReactNode;\n /** Uma frase abaixo do título. Só aparece se `title` existir. */\n description?: React.ReactNode;\n /** O que a linha diz quando `data` chega vazio. */\n emptyLabel?: React.ReactNode;\n /**\n * Contêiner que rola, quando não é a página. O progresso vira o percurso dele,\n * de ponta a ponta. O elemento precisa estar posicionado (`relative`).\n */\n scrollContainer?: React.RefObject;\n}\n\nconst ESTADO = {\n feito: \"feito\",\n agora: \"agora\",\n aseguir: \"a seguir\",\n} as const;\n\nexport function Timeline({\n data,\n title,\n description,\n emptyLabel = \"Nenhuma etapa por aqui ainda.\",\n scrollContainer,\n className,\n ...props\n}: TimelineProps) {\n const listaRef = React.useRef(null);\n const nosRef = React.useRef<(HTMLLIElement | null)[]>([]);\n const semMovimento = useReducedMotion();\n\n /**\n * A fração de cada etapa dentro da lista — medida, não estimada.\n *\n * Dividir 1 pelo número de etapas seria mais curto e estaria errado sempre que\n * uma etapa tem três linhas e a seguinte tem dez: o ponto acenderia antes ou\n * depois de o traço chegar nele, e a linha passaria a discordar de si mesma.\n * Aqui a fração sai do offset real do nó, então traço e ponto são a mesma\n * medida lida duas vezes.\n */\n const [fracoes, setFracoes] = React.useState([]);\n\n React.useEffect(() => {\n const lista = listaRef.current;\n if (!lista) return;\n\n const medir = () => {\n // As duas medidas na mesma régua: com `offsetHeight` dividindo um delta de\n // `getBoundingClientRect`, a fração encolhia junto com o `scale` de quem\n // hospeda a peça, e o ponto acendia antes de o traço chegar nele.\n const caixa = lista.getBoundingClientRect();\n const alturaTotal = caixa.height || 1;\n setFracoes(\n nosRef.current.map((no) =>\n no ? (no.getBoundingClientRect().top - caixa.top) / alturaTotal : 0,\n ),\n );\n };\n\n medir();\n if (typeof ResizeObserver === \"undefined\") return;\n const ro = new ResizeObserver(medir);\n ro.observe(lista);\n return () => ro.disconnect();\n }, [data]);\n\n /*\n * `end 60%`, e não `end 50%`: o traço precisa terminar de encher ANTES de a\n * última etapa sair pela borda de cima, senão a linha nunca é vista completa\n * — a pessoa rola, o traço ainda está a 80% e o conteúdo já acabou.\n */\n const { scrollYProgress } = useScroll(\n scrollContainer\n ? { container: scrollContainer as React.RefObject }\n : { target: listaRef, offset: [\"start 85%\", \"end 60%\"] },\n );\n\n // `scaleY` e não `height`: altura é layout a cada quadro, escala é compositor.\n const escala = useTransform(scrollYProgress, [0, 1], [0, 1]);\n const opacidade = useTransform(scrollYProgress, [0, 0.06], [0, 1]);\n\n const [alcancados, setAlcancados] = React.useState(0);\n useMotionValueEvent(scrollYProgress, \"change\", (p) => {\n setAlcancados(fracoes.filter((f) => f <= p).length);\n });\n /*\n * O evento só avisa quando o progresso MUDA. Se a primeira leitura chega antes\n * de as frações existirem (o normal: as duas nascem no mesmo commit), o nó fica\n * no piso até a pessoa rolar, enquanto o traço já está na posição certa. Era por\n * isso que a mesma peça nascia no último passo numa tela e no primeiro em outra.\n */\n React.useEffect(() => {\n setAlcancados(fracoes.filter((f) => f <= scrollYProgress.get()).length);\n }, [fracoes, scrollYProgress]);\n\n /*\n * Piso de um: linha do tempo sem degrau atual não é linha do tempo.\n *\n * Com `alcancados` em zero — antes de a peça entrar na faixa de rolagem que a\n * preenche — TODOS os nós caíam em \"a seguir\": doze pontos vazios e doze\n * títulos apagados, uma lista morta. Pior, `i === total - 1` virava `i === -1`\n * e nem o \"agora\" existia, então a peça não dizia nada em nenhum dos seus\n * estados. O primeiro marco é o presente por definição; o traço continua em\n * zero e cresce com a rolagem, que é o que ele tem a dizer.\n */\n const total = semMovimento ? data.length : Math.max(1, alcancados);\n\n if (!data.length) {\n return (\n \n

\n {emptyLabel}\n

\n \n );\n }\n\n return (\n
\n {title && (\n
\n

\n {title}\n

\n {description && (\n

\n {description}\n

\n )}\n
\n )}\n\n {/*\n * O trilho é irmão do `
    `, não filho.\n *\n * `
      ` só aceita `
    1. ` (mais `