Files
kandev/docs/plans/quick-chat-activity-indicators/plan.md
T
2026-08-24 11:09:03 +00:00

116 lines
7.0 KiB
Markdown

---
spec: docs/specs/ui/requirements/quick-chat-idle-dot.md
created: 2026-08-23
status: implemented
---
# Implementation Plan: Quick Chat Activity Indicators
## Overview
Extend the existing completion-only Quick Chat dot into a derived running or finished activity state. First add pure selectors, then update tabs and entry icons, and finally cover the real lifecycle in Playwright.
No backend contract changes are necessary. The frontend already receives session state, foreground activity, preparation progress, and completion events.
## Frontend
### Activity selectors
- Add `apps/web/lib/state/slices/ui/quick-chat-activity-selectors.ts`.
- Export `QuickChatActivityState` as `"running" | "finished" | null`.
- Extract the shared live-work predicate to `apps/web/lib/session-working.ts`. Use it from `deriveSessionFlags()` and the Quick Chat selector.
- Add `selectQuickChatSessionIsWorking(state, sessionId)`. Include `prepareProgress.bySessionId[sessionId]?.status === "preparing"`.
- Add `selectQuickChatActivity(state, workspaceId)`. Return `null` while the dialog is open or the workspace is absent.
- For a closed dialog, return `"running"` when any workspace conversation is working. Otherwise, return `"finished"` when the workspace has an unseen marker.
- Keep `quick-chat-unseen-selectors.ts` for the existing marker-level tests and lifecycle helpers.
### Tab status
- Update `apps/web/components/quick-chat/quick-chat-modal.tsx` with a conversation-tab wrapper that reads `selectQuickChatSessionIsWorking` for one session.
- Add an `isWorking` prop to `QuickChatTabItem` in `quick-chat-tab-item.tsx`.
- Render `GridSpinner` before the tab name while `isWorking` is true.
- Do not add a spinner to setup tabs or `QuickTerminalTabItem`.
### Entry activity bubble
- Add `apps/web/components/quick-chat/quick-chat-activity-indicator.tsx` for the shared bubble.
- Use `bg-blue-500` for `running` and `bg-emerald-500` for `finished`.
- Add `data-testid="quick-chat-activity-indicator"`, `data-state`, and `data-legacy-testid="quick-chat-unseen-dot"` during the selector migration.
- Add `apps/web/components/quick-chat/use-quick-chat-activity.ts` to select the aggregate state and resolve the accessible button label.
- Use the shared hook and indicator in these entry points:
- `apps/web/components/app-sidebar/app-sidebar-primary-nav.tsx`
- `apps/web/components/app-sidebar/app-sidebar-new-task-item.tsx`
- `apps/web/components/kanban/kanban-header.tsx`
- `apps/web/components/kanban/kanban-header-mobile.tsx`
- `apps/web/components/task/mobile/quick-chat-sheet-button.tsx`
- Replace the boolean `dot` props in `AppSidebarNavItem` and `RowActionButton` with the typed activity state.
- Add `sidebar:quickChatRunning` in English, Portuguese, Simplified Chinese, Traditional Chinese, and the generated pseudo-locale. Keep `sidebar:quickChatUnseen` for the finished label.
### Mobile parity
This change modifies status content inside existing controls. It does not change composition, navigation, scrolling, or touch behavior.
The nearest mobile exemplars are the current mobile Quick Chat idle dot and the status dot in `session-mobile-bottom-nav.tsx`. Keep the existing mobile header and task-switcher entry points, touch targets, and dismissal behavior.
## Tests
- **What:** The shared working predicate includes `STARTING`, `RUNNING`, and background work.
**File:** `apps/web/lib/session-working.test.ts`.
**How:** Use a table-driven unit test for every session state and foreground activity value.
- **What:** Quick Chat working detection also includes environment preparation.
**File:** `apps/web/lib/state/slices/ui/quick-chat-activity-selectors.test.ts`.
**How:** Use selector tests with two workspaces and two sessions.
- **What:** Running has priority over finished, the dialog suppresses the bubble, and seen results remain clear after close.
**File:** `apps/web/lib/state/slices/ui/quick-chat-activity-selectors.test.ts`.
**How:** Use pure aggregate-state tests.
- **What:** A conversation tab shows the grid spinner only while its session works.
**Files:** `apps/web/components/quick-chat/quick-chat-tab-item.test.tsx` and `quick-chat-modal.test.tsx`.
**How:** Test the tab prop and the modal mapping for server-backed, setup, and terminal tabs.
- **What:** Blue and emerald map to the correct semantic state.
**File:** `apps/web/components/quick-chat/quick-chat-activity-indicator.test.tsx`.
**How:** Use rendered class and `data-state` assertions.
- **What:** Every desktop, tablet, and mobile Quick Chat entry uses the aggregate state and accessible label.
**Files:** Existing sidebar, kanban-header, and mobile task-switcher component tests.
**How:** Use store-backed rendered tests for no activity, running, and finished.
## E2E Tests
- **Scenario:** A real quick-chat turn starts, the tab shows a grid spinner, the dialog closes, and the entry shows the blue state.
**File:** `apps/web/e2e/tests/chat/quick-chat-idle-dot.spec.ts`.
**What to verify:** Tab spinner visibility and the desktop sidebar `data-state="running"` value.
- **Scenario:** The last agent settles while the dialog is closed.
**File:** `apps/web/e2e/tests/chat/quick-chat-idle-dot.spec.ts`.
**What to verify:** The same bubble changes to `data-state="finished"`, then disappears after the dialog opens.
- **Scenario:** The same running-to-finished lifecycle occurs at tablet width.
**File:** `apps/web/e2e/tests/chat/quick-chat-idle-dot.spec.ts`.
**What to verify:** The tablet header uses the same state sequence.
- **Scenario:** The mobile header and task-switcher entry expose the same activity state.
**File:** `apps/web/e2e/tests/chat/mobile-quick-chat-idle-dot.spec.ts`.
**What to verify:** Touch entry, close behavior, blue running state, emerald finished state, and clear-on-open behavior.
The mobile Playwright run is also the focused rendered mobile check. It keeps the existing full-height dialog and touch paths unchanged.
## Verification Results
- Focused frontend tests passed: 10 files, 107 tests.
- `pnpm --filter @kandev/web lint` passed with zero warnings.
- `pnpm --filter @kandev/web run typecheck` passed.
- `pnpm --filter @kandev/web run i18n:check` passed; all supported catalogs are complete and pseudo is in sync.
- `pnpm --filter @kandev/web run i18n:ratchet` passed with zero new violations.
- `pnpm --filter @kandev/web run lint:e2e-sleeps` passed.
- Desktop and tablet Playwright coverage passed: 2 tests.
- Mobile Playwright coverage passed: 2 tests.
- The full `i18n:zh-hant` generator remains blocked by pre-existing residual simplified-Chinese keys in `agents:dynamicProfileSettings`; the targeted `sidebar` conversion completed successfully for this change.
## Implementation Waves And Parallel Candidates
The tasks run sequentially because the UI and E2E work depend on the activity selectors.
- [x] [task-01-activity-selectors](task-01-activity-selectors.md)
- [x] [task-02-activity-ui](task-02-activity-ui.md)
- [x] [task-03-activity-e2e](task-03-activity-e2e.md)
## Open Questions
None. The plan uses blue for running and emerald for finished to match existing Kandev status-dot semantics.