Tooltip

Tooltip (UX) — Design System (Symfony UX Toolkit / shadcn)

BASE CONGELADA (não mude por instância): Fica CONGELADO: a caixa flutuante em bg-foreground / text-background / text-xs, cantos rounded-md, padding px-3 py-1.5, largura máx max-w-xs, gap-1.5 items-center, a seta triangular, a transição opacity+scale duration-200 e o z-50. A11y/semântica imutáveis: role="tooltip", aria-describedby no gatilho, role="presentation" no wrapper, e o par de eventos aparece-no-hover-E-foco / esconde-no-mouseleave-E-blur. Nenhum enricher altera fonte, cor, cantos ou o espaçamento interno da caixa.

USO: <twig:Tooltip />

CAPACIDADES OPT-IN (ligue sem alterar o visual):
- Lado (side): Escolhe de que lado do gatilho a caixa e a seta aparecem: acima, à direita, abaixo ou à esquerda. [position → topo (top) / direita (right) / baixo (bottom) / esquerda (left)]- Alinhamento (align): Desliza a caixa ao longo da borda do gatilho — encostada no início, centralizada ou no fim — mantendo o mesmo lado. [select → início (start) / centro (center) / fim (end)]- Distância do gatilho (sideOffset): Afasta ou aproxima a caixa do gatilho em pixels; é o vão externo entre gatilho e tooltip, não o padding interno da base. [number]- Auto-ajuste na borda (flip): Quando não cabe no lado pedido, vira sozinho para o lado oposto (e a seta acompanha) para não sair da viewport. [toggle]- Atraso de abertura (delay): Milissegundos de espera no hover antes de mostrar, evitando piscadas ao passar o mouse de raspão (hover intent). [number]- Interativo / carência ao fechar: Mantém a caixa aberta enquanto o cursor migra do gatilho para dentro dela, permitindo tooltips com link/texto selecionável. [toggle]- Atalho de teclado (kbd): Anexa um chip de atalho (ex.: ⌘K) ao texto; a base já reserva o slot data-kbd e o estilo do chip, então é só conteúdo aditivo. [text]- Ícone inline: Adiciona um ícone lucide antes ou depois do texto; a base já é items-center com gap-1.5 para acomodá-lo sem mexer no layout. [text → início / fim]- Gatilho por toque/clique: Além de hover/foco, abre no toque ou clique — essencial em telas sem cursor, onde hover não existe. [toggle]FAÇA:
- Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.
- Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.
- Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}.
NÃO FAÇA:
- Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.
- Não crie variante/fork para a mesma coisa — existe UMA base por componente.
- Não reimplemente o componente nem adicione toolchain Node.
TESTE ANTES DE MUDAR: "é função ou é base?" — função = capacidade opt-in; base = mude o token na fonte única (assets/styles/app.css), para todos.

A11Y (herdada da base): A11y/semântica imutáveis: role="tooltip", aria-describedby no gatilho, role="presentation" no wrapper, e o par de eventos aparece-no-hover-E-foco / esconde-no-mouseleave-E-blur

{
    "$schema_version": "1.0",
    "id": "tooltip",
    "component": "Tooltip",
    "eixo": "ux",
    "particularidade": "Tooltip é um overlay flutuante, transitório e ancorado: aparece no hover/foco do gatilho, aponta para ele por lado+seta e mostra ajuda contextual curta com vínculo de acessibilidade (aria-describedby). Sua natureza é POSIÇÃO + TEMPO + GATILHO — é aí que moram os enriquecedores, sem tocar na aparência da caixinha.",
    "base_congelada": "Fica CONGELADO: a caixa flutuante em bg-foreground / text-background / text-xs, cantos rounded-md, padding px-3 py-1.5, largura máx max-w-xs, gap-1.5 items-center, a seta triangular, a transição opacity+scale duration-200 e o z-50. A11y/semântica imutáveis: role=\"tooltip\", aria-describedby no gatilho, role=\"presentation\" no wrapper, e o par de eventos aparece-no-hover-E-foco / esconde-no-mouseleave-E-blur. Nenhum enricher altera fonte, cor, cantos ou o espaçamento interno da caixa.",
    "props": [
        {
            "name": "delayDuration",
            "type": "number",
            "default": "0",
            "description": "Delay in milliseconds before showing the tooltip. Defaults to `0` #}"
        },
        {
            "name": "id",
            "type": "string",
            "default": null,
            "description": "Unique identifier for the tooltip #}"
        }
    ],
    "capacidades": [
        {
            "id": "lado-side",
            "nome": "Lado (side)",
            "descricao": "Escolhe de que lado do gatilho a caixa e a seta aparecem: acima, à direita, abaixo ou à esquerda.",
            "controle": "position",
            "opcoes": [
                "topo (top)",
                "direita (right)",
                "baixo (bottom)",
                "esquerda (left)"
            ],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (position). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "alinhamento-align",
            "nome": "Alinhamento (align)",
            "descricao": "Desliza a caixa ao longo da borda do gatilho — encostada no início, centralizada ou no fim — mantendo o mesmo lado.",
            "controle": "select",
            "opcoes": [
                "início (start)",
                "centro (center)",
                "fim (end)"
            ],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "dist-ncia-do-gatilho-sideoffset",
            "nome": "Distância do gatilho (sideOffset)",
            "descricao": "Afasta ou aproxima a caixa do gatilho em pixels; é o vão externo entre gatilho e tooltip, não o padding interno da base.",
            "controle": "number",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (number). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "auto-ajuste-na-borda-flip",
            "nome": "Auto-ajuste na borda (flip)",
            "descricao": "Quando não cabe no lado pedido, vira sozinho para o lado oposto (e a seta acompanha) para não sair da viewport.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "atraso-de-abertura-delay",
            "nome": "Atraso de abertura (delay)",
            "descricao": "Milissegundos de espera no hover antes de mostrar, evitando piscadas ao passar o mouse de raspão (hover intent).",
            "controle": "number",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (number). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "interativo-car-ncia-ao-fechar",
            "nome": "Interativo / carência ao fechar",
            "descricao": "Mantém a caixa aberta enquanto o cursor migra do gatilho para dentro dela, permitindo tooltips com link/texto selecionável.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "atalho-de-teclado-kbd",
            "nome": "Atalho de teclado (kbd)",
            "descricao": "Anexa um chip de atalho (ex.: ⌘K) ao texto; a base já reserva o slot data-kbd e o estilo do chip, então é só conteúdo aditivo.",
            "controle": "text",
            "opcoes": [],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (text). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "cone-inline",
            "nome": "Ícone inline",
            "descricao": "Adiciona um ícone lucide antes ou depois do texto; a base já é items-center com gap-1.5 para acomodá-lo sem mexer no layout.",
            "controle": "text",
            "opcoes": [
                "início",
                "fim"
            ],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (text). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "gatilho-por-toque-clique",
            "nome": "Gatilho por toque/clique",
            "descricao": "Além de hover/foco, abre no toque ou clique — essencial em telas sem cursor, onde hover não existe.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ux/tooltip; comportamento via controller Stimulus. Não altera a base."
        }
    ],
    "snippet_uso": "<twig:Tooltip />",
    "exemplo_demo": "<twig:Tooltip id=\"tooltip-demo\">\n    <twig:Tooltip:Trigger>\n        <twig:Button {{ ...tooltip_trigger_attrs }} variant=\"outline\">Hover</twig:Button>\n    </twig:Tooltip:Trigger>\n    <twig:Tooltip:Content>\n        <p>Add to library</p>\n    </twig:Tooltip:Content>\n</twig:Tooltip>",
    "regras": {
        "faca": [
            "Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.",
            "Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.",
            "Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}."
        ],
        "nao_faca": [
            "Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.",
            "Não crie variante/fork para a mesma coisa — existe UMA base por componente.",
            "Não reimplemente o componente nem adicione toolchain Node."
        ]
    },
    "a11y": "A11y/semântica imutáveis: role=\"tooltip\", aria-describedby no gatilho, role=\"presentation\" no wrapper, e o par de eventos aparece-no-hover-E-foco / esconde-no-mouseleave-E-blur",
    "mcp": {
        "tool": "get_component",
        "args": {
            "id": "tooltip"
        }
    }
}