influxdata / influxdata/docs-v2

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

Open
#7,706 0 comments 0 reactions 0 assignees View on GitHub
area:site-ui
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## 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 `` 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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the existing Ask AI/Kapa integration and the named Cypress suites: cypress/e2e/content/ask-ai.cy.js and cypress/e2e/topnav.cy.js. Run the listed TypeScript, Hugo, Cypress, and shortcode checks to establish the current behavior. Done means the specified sidebar, composer, responsive, focus, rail, theme, retry, and legacy-trigger scenarios pass across the named pages and viewport sizes.

Written by the indexing model from the issue text.

Assessment

Tech stack
cypress, hugo, javascript, typescript
Domain
documentation, frontend, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.