Skip to content

feat: add hover tooltips for blobl, connect and rpkcmd references - #457

Draft
JakeSCahill wants to merge 2 commits into
mainfrom
feat/macro-tooltips
Draft

JakeSCahill wants to merge 2 commits into
mainfrom
feat/macro-tooltips

Conversation

@JakeSCahill

Copy link
Copy Markdown
Contributor

Adds hover tooltips to the inline references that the new blobl:, connect: and rpkcmd: macros emit (docs-extensions-and-macros #458), in the same way property tooltips work for prop:.

  • Only macro output is decorated, never plain backticks. Tooltips use the data only: if the data, the file or the entry is missing, there's no tooltip.
  • Bloblang: signature, description and parameters with defaults. It shares the renderer and Connect data with the code-block tooltips, which now also show parameter defaults and no longer invent Returns: any.
  • Connect: a component shows its type, a status badge (beta, experimental, deprecated) and its summary. A field shows its type, default and the first sentence of its description.
  • rpk: a command shows its usage line and description. A flag shows the flag, shorthand, type, default and description.
  • New rpk-json-url meta, resolved from streaming's rpk-<version>.json attachment (docs #2255) the same way as properties-json-url.
  • Per-page off switches: :page-disable-bloblang-tooltips:, :page-disable-connect-tooltips:, :page-disable-rpk-tooltips:.
  • Test pages: macro-tooltips-test covers every case, and macro-tooltips-off-test covers the off switches. Both use trimmed real data fixtures that are served only in the preview.

Nothing changes on live pages until #458 ships the macros. rpk tooltips also need docs #2255 to publish the rpk data.

Testing

  • npx gulp lint passes.
  • New tests/macro-tooltips (12 tests) and the 5 new tests/head-meta tests pass, with negative controls.
  • Other suites pass. test:interactive failed once and then passed on four reruns.
  • I hovered every case on a local preview build in light and dark modes, with keyboard focus and Escape.
  • npx gulp preview:build hangs in compile:widgets locally (antora.yml 404); the build and preview-pages tasks run fine directly.

Decorate the inline references the blobl:, connect: and rpkcmd: macros
emit (code.bloblang-call, code.connect-component, code.rpk-command) with
tippy tooltips built only from the published data. A missing dataset or
entry means no tooltip.

- Bloblang reuses 16-bloblang-interactive.js: one shared Connect JSON
  request and the same renderer as code blocks. The renderer now shows
  parameter defaults and no longer invents a return type or description.
  Inline tooltips ignore the hand-written bloblang-docs.json fallback.
- Connect reads the same connect-json-url data: name, type, status badge
  and summary for a component; path, type, default and first sentence
  for a field.
- rpk reads a new rpk-json-url meta, resolved from rpk-<tag>.json in
  streaming the same way the properties tag is chosen.
- Per-family off switches: page-disable-bloblang-tooltips,
  page-disable-connect-tooltips and page-disable-rpk-tooltips.

The tests run against preview-src/_data, Connect and rpk fixtures trimmed
from connect-4.115.1.json and rpk-v26.2.2.json.
Two preview pages cover every case with the macros' real HTML output,
each with a note on what hover should show. The preview build copies the
preview-src/_data fixtures to the UI root, where the tooltip scripts look
in preview mode, so they never ship in the bundle.
@netlify

netlify Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for docs-ui ready!

Name Link
🔨 Latest commit 61a9ef8
🔍 Latest deploy log https://app.netlify.com/projects/docs-ui/deploys/6ae4667fba6a662940946ecc
😎 Deploy Preview https://deploy-preview-457--docs-ui.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 51 (🟢 up 11 from production)
Accessibility: 89 (no change from production)
Best Practices: 83 (no change from production)
SEO: 89 (no change from production)
PWA: -
View the detailed breakdown and full score reports
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant