Redesign the Ask AI chat flow with a persistent composer and right sidebar

[jstirnaman]

Summary

Redesign the existing Kapa integration around a persistent entry point and contextual chat sidebar while retaining Ask AI terminology.

• Show a labeled Ask AI button in the top navigation beside the existing conditional Search icon.
• Replace the floating footer bubble with a centered bottom composer containing #chat-assistant-textarea and the placeholder Ask a question....
• On submission, hide the floating composer, open Kapa in its supported right-sidebar mode, submit the question automatically, and focus the sidebar input.
• Treat Ask AI as the active right rail: hide the API On this page rail while chat is open and establish a reusable contract for future site-wide in-page navigation.
• Keep the existing Kapa Website Widget and product/version filtering. Do not add React or migrate to the Chat SDK.

Implementation changes

• Add an accessible top-navigation <button> labeled Ask AI, using the existing Chat icon and remaining visible while Kapa loads. Preserve the current left-sidebar Search input and conditional top-bar Search icon behavior.
• Replace the footer Ask AI bubble with a first-party composer:
  • Fix it above the bottom edge, center it, and cap it at 386px.
  • Support multiline input, Enter to submit, Shift+Enter for a newline, a disabled send button for whitespace-only input, and an aria-live status region.
  • Display it immediately on standard pages, including the homepage and feature board; hide it in print and on the 404 page.
• Configure Kapa with viewMode: "sidebar", a 386px modal width, hidden launcher and overlay, unlocked page scrolling, mobile full-screen behavior, and InfluxData light and dark colors. Remove legacy modal sizing and centering attributes that conflict with sidebar mode.
• Convert the Ask AI controller to TypeScript and make it the single owner of initialization, readiness, triggers, and state:
  • Header click opens an empty sidebar.
  • Floating composer calls Kapa.open({ mode: "ai", query, submit: true }).
  • Existing .ask-ai-open shortcode, code-block, and detector links continue to support prefilled questions and source-group filtering.
  • If submission occurs before Kapa is ready, retain the question and complete the queued open after load.
  • If loading fails, leave the composer visible, re-enable submission, and show a retryable status message.
• Coordinate the two composer surfaces instead of physically reparenting the textarea. After handoff, hide the first-party composer and focus Kapa's sidebar textarea. Preserve Kapa's conversation instance so closing and reopening retains history.
• Drive layout through a body-level Ask AI state and shared right-rail marker:
  • Above 1280px, reserve 386px on the right, hide [data-page-rail], and keep article content unobscured.
  • From 601px through 1280px, use the fixed sidebar as an overlay without squeezing the article.
  • At phone widths, use Kapa's full-screen mobile presentation.
  • Mark existing API TOCs as [data-page-rail]; future site-wide TOCs can adopt the same marker without changing chat logic.
  • Restore the rail, layout, floating composer, and initiating control's focus when chat closes.
  • Reposition the remaining fixed custom-time widget while the wide-screen chat rail is open.
• Expose the active theme on the body with a stable data-theme="light|dark" value and configure Kapa's color-scheme selector against it.

Interfaces and state

• Extend the internal window.Kapa TypeScript contract with typed open, close, render, event registration, and source-group methods.
• Introduce stable DOM contracts:
  • data-component="ask-ai" for the controller root.
  • data-ask-ai-action="open|submit" for controls.
  • data-ask-ai-state="loading|ready|opening|open|error" on the body.
  • [data-page-rail] for mutually exclusive right-rail content.
  • --ask-ai-rail-width: 386px for shared layout calculations.
• Register onModalOpen, onModalClose, and onAskAIQuerySubmit once. Clear the pre-chat draft only after Kapa accepts the submission.

Test plan

• Refactor the Ask AI Cypress suite to stub Kapa deterministically and verify:
  • Initial top-bar button and floating composer visibility.
  • Empty-input validation, Enter and Shift+Enter behavior, and send-button state.
  • Exact query handoff with submit: true, including special characters.
  • Sidebar state, focus transfer, composer hiding, and AI response rendering in the mocked conversation.
  • Header opening without automatic submission.
  • Close and reopen behavior, focus restoration, retained conversation history, and restored page rail.
  • Existing shortcode, code-block, and product-specific source-filter behavior.
  • Script-load failure and retry behavior without losing the draft.
• Exercise responsive states at 1440px, 1024px, and 390px; verify wide reflow, medium overlay, mobile full-screen behavior, and absence of horizontal page overflow.
• Test an API page, regular article, homepage, and feature-board page in both themes. Confirm the API TOC is hidden only while Ask AI owns the rail.
• Run:
  • yarn build:ts
  • npx hugo --quiet
  • Hugo runtime server checks with HTTP 200 responses for representative regular, API, and homepage URLs
  • node cypress/support/run-e2e-specs.js --spec "cypress/e2e/content/ask-ai.cy.js" --no-mapping
  • node cypress/support/run-e2e-specs.js --spec "cypress/e2e/topnav.cy.js" --no-mapping
  • yarn test:shortcode-examples
• Perform browser QA for keyboard-only operation, visible focus, close-focus restoration, screen-reader labels and status, theme synchronization, page scrolling, and JavaScript console errors.

Assumptions

• Ask AI remains the user-facing name everywhere.
• The site-wide On this page rollout is not part of this change; this redesign only establishes and validates the shared right-rail contract.
• Existing Kapa configuration, analytics, disclaimers, MCP menu, product questions, and source-group behavior remain intact unless they conflict with sidebar presentation.