Agent Hint
Agent Hint (`<pura-agent-hint>`) is an agent-native, headless component that holds text hidden from human eyes (the sr-only technique) but present in the DOM and the accessibility tree. Use it to give a screen reader or automated agent extra context about a neighboring control, connecting via `for` to the target's `aria-describedby`. Beyond ARIA, it exposes a machine-readable layer: stable `data-*` attributes and a global registry `window.__puraAgentHints` (a Map with `query(forId)`) that agents can enumerate to read every hint on the page.
Preview
<label for="cupom">Coupon code</label>
<input id="cupom" type="text" placeholder="e.g. PURA10" />
<pura-agent-hint for="cupom" level="tip">
Enter the coupon in uppercase, with no spaces. Only one coupon per order.
</pura-agent-hint>
<!-- Agents can enumerate every hint on the page:
window.__puraAgentHints.query("cupom") -->Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
for | string | — | id of the control this hint describes. When set, it connects the target's aria-describedby to a stable internal id so the hint is announced for that control. |
role | string | note | Accessibility role exposed on the host. |
label | string | — | Optional aria-label for the hint region. |
level | "info" | "tip" | "warning" | info | Machine-readable semantic weight. Surfaces as data-level and aria-roledescription (agent hint / agent tip / agent warning). |
visible | boolean | false | Opt-in escape hatch: renders the hint visibly (for debugging / authoring). |
Installation
pura is copy-paste and dependency-free. Load the whole library, or just this component.
<link rel="stylesheet" href="/pura/tokens.css">
<script type="module" src="/pura/lib/agent-hint.js"></script>import "./pura/lib/agent-hint.js";