{# P1-T17: reusable CSS-only help-tooltip macro.
Renders a small ``?`` glyph that, on hover or keyboard focus, expands
into a labelled tooltip block. Used across the Trace, LLM Explorer,
and Registry surfaces (P2-T16 / P4-T19 apply it per-cell).
Design contract
---------------
* Pure CSS -- no JavaScript dependency. Hover via ``:hover`` and
keyboard via ``:focus-within`` so screen-reader / keyboard users
can read the same content as mouse users.
* Colours come from ``admin_t55_styles.html`` (the T55 design tokens).
The ``?`` ink is ``--ink-3`` (low-emphasis annotation); the tooltip
body sits on ``--bg-2`` with a ``--rule-2`` border and ``--ink-2``
text -- matches the rest of the admin chrome.
* The tooltip floats above the surrounding layout (``position: absolute``
on a relatively-positioned wrapper) so it never reflows the row it
annotates.
* ARIA: the ``?`` button carries ``aria-describedby`` pointing at the
tooltip body, which carries ``role="tooltip"``. Screen readers
announce the tooltip text on focus.
* Esc-to-dismiss is handled implicitly: ``:focus-within`` retracts the
tooltip the moment focus leaves the button, so pressing Esc (which
most browsers map to "blur the focused element" on a tooltip
trigger) collapses it.
Styles are emitted by the separate ``tip_styles()`` macro: call it
ONCE near the top of any template that uses ``{{ tip(...) }}`` (for
example, just inside ```` or below the page's main ``
{%- endmacro -%}
{# Public macro. ``text`` is the human-readable help string;
``position`` is one of ``top`` / ``bottom`` / ``left`` / ``right``
(defaults to ``top``). Any other value falls back to ``top`` so a
typo doesn't break the layout. #}
{% macro tip(text, position="top") -%}
{%- set _safe_position = position if position in ('top', 'bottom', 'left', 'right') else 'top' -%}
{%- set _tip_id = 'rc-tip-' ~ range(100000, 999999) | random -%}
{{ text }}
{%- endmacro %}
{#
Example usage:
{% from 'partials/help_tooltip.html' import tip, tip_styles %}
...
{{ tip_styles() }}
Cost {{ tip("Cost rolled up from all LLM calls within this step's window.") }}
Status {{ tip("Step status: complete, errored, partial, or in-progress.", position="right") }}