{
"name": "Toggletip",
"source": "src/components/Toggletip.tsx",
"propsType": "ToggletipProps",
"description": "Toggletip — an \"ⓘ\" that opens an explanation on click, with room for a link.\n\nWHY NOT TOOLTIP, AND WHY NOT POPOVER\n\nA Tooltip opens on hover, closes on pointer-out and cannot be focused, so a\nlink in one is unreachable — and a hover-only hint is invisible on touch.\nA Popover is a dialog: it takes focus, traps it, and hides the rest of the\npage from assistive technology, which is a lot of ceremony for a sentence of\nhelp beside a label. A toggletip sits between: opened on purpose, it stays\nopen, and it is part of the page.\n\nHOW IT IS BUILT\n\n - The bubble is rendered right after the button in the DOM, not portalled,\n so the next Tab from the button lands on a link inside it. It is\n positioned with `useOverlayPosition`, which measures against the\n bubble's own containing block, so it still flips and stays on screen.\n - Focus stays on the button when it opens. The bubble is a live region\n that is always in the page — empty while closed — so its text is read\n out on open without focus having to move. The same reason TableBatchBar\n stays mounted: a live region inserted with its message is silent.\n - It closes on Escape (focus back to the button), on a press outside, and\n when focus leaves the button and bubble together. It never traps focus\n and never hides the page — it is not modal.",
"import": "import { Toggletip } from 'ionbase-ui';",
"status": "stable",
"summary": "An \"ⓘ\" button that opens a short explanation on click and keeps it open, so it can hold a link. Not modal, not hover.",
"useWhen": [
"a field label or a setting needs a sentence of explanation that most people will not need",
"the explanation links onward — \"How retention works\" — which a Tooltip cannot hold"
],
"useInstead": [
{
"when": "naming an icon-only control, or a hint with nothing to click in it",
"use": "Tooltip",
"why": "a tooltip needs no press to read; a toggletip for a one-word hint makes people click to learn what hovering would have told them"
},
{
"when": "the content is a task — a form, a choice, anything more than a sentence and a link",
"use": "Popover",
"why": "that is a dialog: it takes focus, traps it and has a title; a toggletip is part of the page"
},
{
"when": "the information is needed to fill the field in",
"use": "Input",
"why": "`description` is always visible; hiding required guidance behind an ⓘ makes people find it by failing first"
},
{
"when": "the explanation is that content was generated by AI",
"use": "AILabel",
"why": "the mark is the button, and it requires saying what was generated and from what"
}
],
"composition": {
"order": [
"Toggletip",
"Link"
],
"note": "Place it right after the label text it explains. The children are a sentence or two and at most one Link or Button. Name it for its subject — `aria-label=\"About log retention\"`.",
"example": "<>Keep run logs for Logs past the period are deleted every night. How retention works"
},
"variants": {
"placement": {
"top": {
"use": "the default — above the label, clear of the field below"
},
"bottom": {
"use": "near the top of the viewport; it also flips here on its own"
},
"left": {
"use": "beside a label at the end of a row"
},
"right": {
"use": "beside a label at the start of a row"
}
},
"size": {
"sm": {
"use": "beside body-sm text — field labels, table headers"
},
"md": {
"use": "beside body text — headings of settings rows"
}
}
},
"slots": {
"children": {
"accepts": "text, Link, Button",
"note": "the explanation; read out on open"
}
},
"a11y": {
"role": "button with aria-expanded and aria-controls, controlling a status region",
"guarantees": [
"opens on click, Enter or Space — never on hover, so it works the same on touch",
"the bubble follows the button in the DOM, so the next Tab reaches a link inside it",
"the bubble is a `role=\"status\"` live region that is in the page before it opens, so its text is read out on open while focus stays on the button",
"Escape closes it and returns focus to the button; inside a Modal, the first Escape closes only the toggletip",
"a press outside, or focus leaving the button and bubble together, closes it",
"not modal: no focus trap, nothing on the page hidden from assistive technology",
"a 24px target at both sizes, pulled into the line so the label is no taller for having one"
],
"requires": [
"`aria-label` naming what it explains — \"About log retention\", not \"Info\" or \"More information\""
],
"notes": [
"The bubble is rendered inline, not portalled — that is what keeps it in the Tab order. It is clipped only by an ancestor that is BOTH positioned and clipping (`position` other than static, with `overflow` hidden, auto or scroll): plain `overflow: hidden` does not clip an absolutely positioned descendant whose containing block is higher up. Table's scroll container is exactly that pair, so keep toggletips out of table headers; the demo's smoke test hit-tests the bubble's corners to catch the case.",
"Inside a