Files
kandev/apps/web/components/task/chat/clarification-input-overlay.tsx
T
José Almeida af9d3547a6 feat(web): clearer custom-answer state and Cmd+Enter submit on clarifications (#934)
* feat(web): add clearAnswer + submit re-entry guard to useClarificationGroup

clearAnswer removes a stored answer so emptying a clarification draft can
revert the stepper to "unanswered". A small inflight ref in submitCollected
/ skipAll prevents duplicate POSTs when multiple submit paths race (e.g.
Cmd+Enter inside the custom input commits the draft and also asks the
parent to finalize the batch).

* feat(web): show selected state and Cmd+Enter submit on clarification custom input

The "Or type a custom answer…" input previously had no selected styling and
needed an Enter keypress before the carousel stepper marked the question as
answered, which made it easy to lose track of which path was the active
answer. Now:

- Typing into the custom input live-records the draft, so the stepper and
  group progress update immediately and the input picks up the same blue
  ring + check icon used by selected options. When custom is active, any
  previously picked option visually deselects (they are mutually exclusive
  at commit time).
- Picking an option after typing wipes that question's draft so the visible
  input and committed answer stay in sync.
- Cmd/Ctrl+Enter submits the bundle when every question is answered — from
  inside the custom input (commits the draft then finalises) and from
  anywhere else in the overlay. Inside the input is handled locally so
  submitCollected does not fire twice.

* test(web): cover live-record + Cmd+Enter clarification UX

Adds four cases over the existing clarification-multi mock scenario:
typing auto-selects custom and deselects the option, emptying the draft
reverts the stepper, Cmd+Enter from the last-step custom input submits
the bundle, and Cmd+Enter from outside the input submits when all answered.
Adds a session-page locator for the new custom-input container so the
data-active attribute can be asserted.

* fix(web): address bot review feedback on clarification UX

- Cmd/Ctrl+Enter inside the custom-text input no longer calls the
  per-question commit path. The draft is already live-recorded via
  onChange, so calling onSubmit here only added a stale advance-to-next
  step before the bundle was submitted. Now Cmd+Enter just finalises.
- handleSubmit depends on group.submitCollected (which the hook memoises)
  rather than the whole group object, so it no longer re-creates on every
  keystroke through the live-record path.
- Add a unit test that fires submitCollected twice concurrently and
  asserts the inflight ref keeps the wire count at 1 — direct coverage
  for the guard introduced in the previous commit instead of relying on
  the 409 round-trip test.
2026-05-18 22:32:16 +01:00

500 lines
16 KiB
TypeScript

"use client";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { IconX, IconMessageQuestion, IconInfoCircle } from "@tabler/icons-react";
import ReactMarkdown from "react-markdown";
import { markdownComponents, remarkPlugins } from "@/components/shared/markdown-components";
import type {
Message,
ClarificationRequestMetadata,
ClarificationAnswer,
ClarificationQuestion,
} from "@/lib/types/http";
import { useClarificationGroup } from "@/hooks/domains/session/use-clarification-group";
import {
ClarificationCarouselNav,
ClarificationCustomInput,
ClarificationOptions,
ClarificationStepper,
} from "./clarification-overlay-parts";
type ClarificationInputOverlayProps = {
messages: readonly Message[] | null | undefined;
onResolved: () => void;
};
type SingleQuestionMeta = {
message: Message;
metadata: ClarificationRequestMetadata;
question: ClarificationQuestion;
questionId: string;
};
function readSingleQuestionMeta(message: Message | null | undefined): SingleQuestionMeta | null {
if (!message) return null;
const metadata = message.metadata as ClarificationRequestMetadata | undefined;
if (!metadata?.question) return null;
const questionId = metadata.question_id ?? metadata.question.id;
if (!questionId) return null;
return { message, metadata, question: metadata.question, questionId };
}
function resolveQuestionMessages(messages: readonly Message[] | null | undefined): Message[] {
if (messages && messages.length > 0) return [...messages];
return [];
}
function sortMessagesByQuestionIndex(messages: Message[]): Message[] {
return messages.slice().sort((a, b) => {
const ai = (a.metadata as ClarificationRequestMetadata | undefined)?.question_index ?? 0;
const bi = (b.metadata as ClarificationRequestMetadata | undefined)?.question_index ?? 0;
return ai - bi;
});
}
type CardProps = {
meta: SingleQuestionMeta;
index: number;
total: number;
selectedOption: string | null;
customCommittedText: string | null;
customDraft: string;
customActive: boolean;
isSubmitting: boolean;
showAgentDisconnected: boolean;
onSelectOption: (optionId: string) => void;
onCustomDraftChange: (text: string) => void;
onSubmitCustom: (text: string) => void;
onRequestFinalSubmit: () => void;
};
function ClarificationCard(props: CardProps) {
const {
meta,
index,
total,
selectedOption,
customCommittedText,
customDraft,
customActive,
isSubmitting,
showAgentDisconnected,
onSelectOption,
onCustomDraftChange,
onSubmitCustom,
onRequestFinalSubmit,
} = props;
const { question, metadata } = meta;
return (
<div
data-testid="clarification-question-card"
data-question-id={meta.questionId}
data-question-index={String(index)}
className="px-4 pt-3 pb-4"
>
<div className="flex items-center gap-2 mb-2 text-xs text-muted-foreground">
<IconMessageQuestion className="h-4 w-4 text-blue-500" />
{total > 1 && (
<span data-testid="clarification-progress-chip">
Question {index + 1} of {total}
</span>
)}
{metadata.question.title && (
<span className="text-muted-foreground/70">
{total > 1 ? "· " : ""}
{metadata.question.title}
</span>
)}
</div>
<div className="markdown-body max-w-none text-sm font-medium [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 mb-3">
<ReactMarkdown remarkPlugins={remarkPlugins} components={markdownComponents}>
{question.prompt}
</ReactMarkdown>
</div>
<ClarificationOptions
options={question.options}
selectedOption={selectedOption}
isSubmitting={isSubmitting}
customActive={customActive}
onSelectOption={onSelectOption}
/>
{showAgentDisconnected && (
<div
data-testid="clarification-deferred-notice"
className="mt-2 text-xs text-amber-500/90 flex items-center gap-1.5"
>
<IconInfoCircle className="h-3.5 w-3.5 flex-shrink-0" />
The agent has moved on. Your response will be sent as a new message.
</div>
)}
<ClarificationCustomInput
draft={customDraft}
isSubmitting={isSubmitting}
committedText={customCommittedText}
active={customActive}
onChange={onCustomDraftChange}
onSubmit={onSubmitCustom}
onRequestFinalSubmit={onRequestFinalSubmit}
/>
</div>
);
}
function useResolveCallback(
submitState: ReturnType<typeof useClarificationGroup>["submitState"],
onResolved: () => void,
) {
const last = useRef(submitState);
useEffect(() => {
if (last.current !== submitState && submitState === "ok") {
onResolved();
}
last.current = submitState;
}, [submitState, onResolved]);
}
type CarouselShortcutArgs = {
meta: SingleQuestionMeta;
activeIndex: number;
total: number;
canSubmit: boolean;
onPick: (index: number) => void;
onPrev: () => void;
onNext: () => void;
onSkip: () => void;
onSubmit: () => void;
};
// shouldIgnoreShortcut filters out events that the overlay must not handle:
// keystrokes inside an input/textarea (the user is typing) and any modifier
// combo (so we don't hijack browser shortcuts like Cmd/Ctrl+1..9 for tab
// switching or Alt+ArrowLeft for back-navigation).
function shouldIgnoreShortcut(e: KeyboardEvent): boolean {
if (
e.target instanceof HTMLElement &&
(e.target.tagName === "INPUT" || e.target.tagName === "TEXTAREA")
) {
return true;
}
return e.metaKey || e.ctrlKey || e.altKey || e.shiftKey;
}
// tryHandleMetaEnter returns true when the event was Cmd/Ctrl+Enter, so the
// caller can short-circuit. When focus is inside the custom-text input it
// returns true *without* invoking onSubmit — the input's own keydown handler
// owns that path and is responsible for committing the draft + final submit.
function tryHandleMetaEnter(e: KeyboardEvent, canSubmit: boolean, onSubmit: () => void): boolean {
if (e.key !== "Enter" || e.shiftKey || e.altKey) return false;
if (!e.metaKey && !e.ctrlKey) return false;
const inEditable =
e.target instanceof HTMLElement &&
(e.target.tagName === "INPUT" || e.target.tagName === "TEXTAREA");
if (inEditable) return true;
e.preventDefault();
if (canSubmit) onSubmit();
return true;
}
function CarouselKeyboardShortcuts(args: CarouselShortcutArgs) {
const optionsCount = args.meta.question.options.length;
const isLast = args.activeIndex === args.total - 1;
const { canSubmit, onPick, onPrev, onNext, onSkip, onSubmit } = args;
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
if (tryHandleMetaEnter(e, canSubmit, onSubmit)) return;
if (shouldIgnoreShortcut(e)) return;
if (e.key === "Escape") {
e.preventDefault();
onSkip();
return;
}
if (e.key === "ArrowLeft") {
e.preventDefault();
onPrev();
return;
}
if (e.key === "ArrowRight") {
e.preventDefault();
if (isLast && canSubmit) onSubmit();
else onNext();
return;
}
const num = Number.parseInt(e.key, 10);
if (Number.isFinite(num) && num >= 1 && num <= optionsCount) {
e.preventDefault();
onPick(num - 1);
}
};
window.addEventListener("keydown", onKey);
return () => window.removeEventListener("keydown", onKey);
}, [optionsCount, isLast, canSubmit, onPick, onPrev, onNext, onSkip, onSubmit]);
return null;
}
type CarouselBodyProps = {
sortedMessages: Message[];
group: ReturnType<typeof useClarificationGroup>;
activeIndex: number;
setActiveIndex: (idx: number) => void;
customDrafts: Record<string, string>;
setCustomDrafts: React.Dispatch<React.SetStateAction<Record<string, string>>>;
};
type QuestionHandlerCtx = {
meta: SingleQuestionMeta;
group: ReturnType<typeof useClarificationGroup>;
isSingleQuestion: boolean;
activeIndex: number;
total: number;
setActiveIndex: (idx: number) => void;
setCustomDrafts: React.Dispatch<React.SetStateAction<Record<string, string>>>;
};
type QuestionHandlers = {
onSelectOption: (optionId: string) => void;
onCustomDraftChange: (value: string) => void;
onSubmitCustom: (text: string) => void;
};
type SelectionState = {
selectedOption: string | null;
customCommittedText: string | null;
draft: string;
customActive: boolean;
};
function deriveSelectionState(
meta: SingleQuestionMeta,
answers: Record<string, ClarificationAnswer>,
customDrafts: Record<string, string>,
): SelectionState {
const stored = answers[meta.questionId];
const selected = stored?.selected_options ?? [];
const selectedOption = selected.length > 0 ? selected[0] : null;
const customCommittedText = stored?.custom_text ?? null;
const draft = customDrafts[meta.questionId] ?? "";
const hasCustomText = draft.trim().length > 0 || (customCommittedText?.length ?? 0) > 0;
const customActive = !selectedOption && hasCustomText;
return { selectedOption, customCommittedText, draft, customActive };
}
function buildQuestionHandlers(ctx: QuestionHandlerCtx): QuestionHandlers {
const { meta, group, isSingleQuestion, activeIndex, total, setActiveIndex, setCustomDrafts } =
ctx;
// Records the answer, then auto-submits (single-question — uses the override
// path because setState is async) or auto-advances to the next step.
const commitAnswer = (answer: ClarificationAnswer) => {
group.recordAnswer(meta.questionId, answer);
if (isSingleQuestion) {
void group.submitCollected({ [meta.questionId]: answer });
return;
}
if (activeIndex < total - 1) setActiveIndex(activeIndex + 1);
};
return {
onSelectOption(optionId) {
// Picking an option wipes any in-flight draft so the answer state and
// the visible input agree (custom_text and selected_options are mutually
// exclusive at commit time).
setCustomDrafts((prev) => {
if (!prev[meta.questionId]) return prev;
return { ...prev, [meta.questionId]: "" };
});
commitAnswer({ question_id: meta.questionId, selected_options: [optionId] });
},
// Live-record the draft so the stepper updates and the custom input lights
// up the moment the user types. Emptying the draft clears the answer so
// allAnswered reverts to false. Enter/Cmd+Enter still drives advance/submit.
onCustomDraftChange(value) {
setCustomDrafts((prev) => ({ ...prev, [meta.questionId]: value }));
const trimmed = value.trim();
if (trimmed.length === 0) {
group.clearAnswer(meta.questionId);
return;
}
group.recordAnswer(meta.questionId, {
question_id: meta.questionId,
selected_options: [],
custom_text: trimmed,
});
},
onSubmitCustom(text) {
const trimmed = text.trim();
if (!trimmed) return;
commitAnswer({
question_id: meta.questionId,
selected_options: [],
custom_text: trimmed,
});
},
};
}
function ClarificationCarouselBody({
sortedMessages,
group,
activeIndex,
setActiveIndex,
customDrafts,
setCustomDrafts,
}: CarouselBodyProps) {
const total = sortedMessages.length;
const activeMessage = sortedMessages[Math.min(activeIndex, total - 1)] ?? null;
const meta = activeMessage ? readSingleQuestionMeta(activeMessage) : null;
const showAgentDisconnectedAtTop = sortedMessages.some(
(m) => (m.metadata as ClarificationRequestMetadata | undefined)?.agent_disconnected === true,
);
const isSubmitting = group.submitState === "submitting";
const isSingleQuestion = total === 1;
const allAnswered = sortedMessages.every((m) => {
const id = readSingleQuestionMeta(m)?.questionId;
return id ? Boolean(group.answers[id]) : false;
});
// group is a fresh object every render, but its submitCollected callback is
// memoised by the hook — depend on the function only so this useCallback
// doesn't churn on every keystroke (via the live-record path).
const submitCollected = group.submitCollected;
const handleSubmit = useCallback(() => {
if (allAnswered) void submitCollected();
}, [allAnswered, submitCollected]);
if (!meta) return null;
const { selectedOption, customCommittedText, draft, customActive } = deriveSelectionState(
meta,
group.answers,
customDrafts,
);
const { onSelectOption, onCustomDraftChange, onSubmitCustom } = buildQuestionHandlers({
meta,
group,
isSingleQuestion,
activeIndex,
total,
setActiveIndex,
setCustomDrafts,
});
return (
<>
<ClarificationCard
meta={meta}
index={activeIndex}
total={total}
selectedOption={selectedOption}
customCommittedText={customCommittedText}
customDraft={draft}
customActive={customActive}
isSubmitting={isSubmitting}
showAgentDisconnected={activeIndex === 0 && showAgentDisconnectedAtTop}
onSelectOption={onSelectOption}
onCustomDraftChange={onCustomDraftChange}
onSubmitCustom={onSubmitCustom}
onRequestFinalSubmit={handleSubmit}
/>
{!isSingleQuestion && (
<ClarificationCarouselNav
activeIndex={activeIndex}
total={total}
isSubmitting={isSubmitting}
onPrev={() => setActiveIndex(Math.max(0, activeIndex - 1))}
onNext={() => setActiveIndex(Math.min(total - 1, activeIndex + 1))}
onSubmit={handleSubmit}
canSubmit={allAnswered}
/>
)}
<CarouselKeyboardShortcuts
meta={meta}
activeIndex={activeIndex}
total={total}
canSubmit={allAnswered}
onPick={(idx) => onSelectOption(meta.question.options[idx].option_id)}
onPrev={() => setActiveIndex(Math.max(0, activeIndex - 1))}
onNext={() => setActiveIndex(Math.min(total - 1, activeIndex + 1))}
onSkip={() => void group.skipAll("User skipped")}
onSubmit={handleSubmit}
/>
</>
);
}
export function ClarificationInputOverlay({
messages,
onResolved,
}: ClarificationInputOverlayProps) {
const sortedMessages = useMemo(
() => sortMessagesByQuestionIndex(resolveQuestionMessages(messages)),
[messages],
);
const group = useClarificationGroup(sortedMessages);
const [customDrafts, setCustomDrafts] = useState<Record<string, string>>({});
const [rawActiveIndex, setActiveIndex] = useState(0);
// Clamp the active index to the current bundle size so late-arriving
// messages or shrunk bundles never put us out of range.
const total = sortedMessages.length;
const activeIndex = total === 0 ? 0 : Math.min(rawActiveIndex, total - 1);
useResolveCallback(group.submitState, onResolved);
if (sortedMessages.length === 0) return null;
const isSubmitting = group.submitState === "submitting";
const isAnsweredAt = (index: number) => {
const m = sortedMessages[index];
if (!m) return false;
const id = readSingleQuestionMeta(m)?.questionId;
return id ? Boolean(group.answers[id]) : false;
};
return (
<div className="relative" data-testid="clarification-overlay">
<div className="flex items-center justify-between gap-3 px-4 pt-3 pb-2">
<div className="flex items-center gap-3">
{total > 1 && (
<ClarificationStepper
total={total}
activeIndex={activeIndex}
isAnswered={isAnsweredAt}
onJump={setActiveIndex}
isSubmitting={isSubmitting}
/>
)}
{total > 1 && (
<span
data-testid="clarification-group-progress"
className="text-xs text-muted-foreground"
>
{group.answeredCount} of {group.total} answered
</span>
)}
</div>
<button
type="button"
onClick={() => void group.skipAll("User skipped")}
disabled={isSubmitting}
className="text-muted-foreground hover:text-foreground cursor-pointer disabled:opacity-50"
data-testid="clarification-skip"
aria-label="Skip all questions"
>
<IconX className="h-4 w-4" />
</button>
</div>
<ClarificationCarouselBody
sortedMessages={sortedMessages}
group={group}
activeIndex={activeIndex}
setActiveIndex={setActiveIndex}
customDrafts={customDrafts}
setCustomDrafts={setCustomDrafts}
/>
</div>
);
}
export type { ClarificationAnswer };