/**
 * Questionnaire types — the kit-neutral contract for an agent's interactive
 * "ask" form rendered inside (or pinned next to) a chat.
 *
 * Deliberately transport-free and host-decoupled: the host owns the wire
 * (SSE/WS payloads), the draft state, and submission; this module only
 * renders one controlled card. Mirrors the cmdop Go `core/interaction`
 * bounds (1–3 questions, 2–4 options, short chip headers) without importing
 * any host domain package.
 */

export type QuestionnaireQuestionMode =
  | 'single_choice'
  | 'multiple_choice'
  | 'text';

export interface QuestionnaireOption {
  id: string;
  label: string;
  description?: string;
}

export interface QuestionnaireQuestion {
  id: string;
  /** Short chip label shown as the fieldset legend (≤12 chars by contract). */
  header?: string;
  /** Full question wording. */
  prompt: string;
  mode: QuestionnaireQuestionMode;
  required?: boolean;
  options?: readonly QuestionnaireOption[];
  /** Presentation-only "Recommended" chip on one option. */
  recommendedOptionId?: string;
  /** Show the free-text escape hatch under the options. */
  allowOther?: boolean;
  /** multiple_choice bounds; default 1..options.length. */
  minSelections?: number;
  maxSelections?: number;
}

export interface Questionnaire {
  /** Optional card title; falls back to labels.title. */
  title?: string;
  questions: readonly QuestionnaireQuestion[];
}

/** Host-owned draft: what the user has picked/typed so far, per question id. */
export interface QuestionnaireDraft {
  selectedIds: Readonly<Record<string, readonly string[]>>;
  other: Readonly<Record<string, string>>;
}

/**
 * Card lifecycle. `pending`/`submitting`/`error` render the interactive form;
 * the terminal states collapse to a one-line receipt.
 */
export type QuestionnaireStatus =
  | 'pending'
  | 'submitting'
  | 'error'
  | 'answered'
  | 'declined'
  | 'expired';

/** Visual labels — i18n is the host's job; English defaults ship in the card. */
export interface QuestionnaireLabels {
  title: string;
  needsYou: string;
  sending: string;
  retryStatus: string;
  required: string;
  optional: string;
  otherAnswer: string;
  yourAnswer: string;
  otherPlaceholder: string;
  textPlaceholder: string;
  recommended: string;
  submit: string;
  submitting: string;
  decline: string;
  retry: string;
  dismiss: string;
  completeOrDecline: string;
  draftPreserved: string;
  answered: string;
  declined: string;
  expired: string;
  selectionRange: (min: number, max: number) => string;
}
