@dataimago/interview 0.2.0-alpha.0 → 0.2.0-alpha.1

package/dist/index.d.ts

@@ -23,38 +23,108 @@ declare function ProgressBar({ current, total, estimatedMinutesRemaining }: Prop
  * @dataimago/interview — schema contract.
  *
  * The types in this file are the package's public contract. Consumers
- * (apps/hub during the iteration-3-B.1 transition; dissertation-ai +
- * sgpc-ai + rpkg-ai once they consume the package) populate the actual
- * question content conforming to these shapes; the components in this
- * package render whatever the consumer provides.
+ * (Level-2 hubs like dissertation-ai, future sgpc-ai, future rpkg-ai)
+ * populate the actual question content conforming to these shapes; the
+ * components in this package render whatever the consumer provides.
  *
- * Extracted from `apps/hub/src/lib/interview-questions.ts` (the
- * `InterviewQuestion` + `QuestionInputType` definitions) and
- * `apps/hub/src/lib/interview-store.ts` (the `InterviewAnswers`
- * record) during iteration-3-B.1 (2026-05-07).
+ * Originally extracted from `apps/hub/src/lib/interview-questions.ts` +
+ * `apps/hub/src/lib/interview-store.ts` during iteration-3-B.1 (2026-05-07).
+ * Extended for the dissertation-ai use case during D.2.1.b (2026-06-02) —
+ * see CHANGELOG for the new question types and the `select` → `single-select`
+ * rename.
  *
  * Design authority: `dataimago-design/wiki/patterns/onboarding-interview.md`.
  */
 /**
  * The set of input shapes the interview engine knows how to render.
  *
+ * Scalar-answer types (value is a `string` or `string[]`):
  * - `short-text` — single-line text field
  * - `long-text` — multi-line textarea
- * - `select` — single-choice radio group with `options[]`
+ * - `single-select` — single-choice radio group with `options[]`
+ *   *(Renamed from `select` in v0.3; `select` is no longer recognized.)*
  * - `multi-select` — multi-choice checkbox group with `options[]`
- * - `scale` — numeric slider 1–N (consumer specifies range via `options[]`
- *   labels; engine renders as a horizontal scale)
+ * - `scale` — numeric slider 1–N
  * - `list` — variable-length list of short-text items, bounded by `listRange`
+ * - `date` — single ISO 8601 date string (`<input type="date">`)
+ *
+ * Compound-answer types (value is a `Record` or `Record[]`):
+ * - `composite` — fixed set of sub-questions answered once. Value is
+ *   `Record<subQuestionId, AnswerValue>`. Sub-questions live on
+ *   `InterviewQuestion.subQuestions`.
+ * - `repeater` — variable-length list of records, each conforming to
+ *   `itemSchema`. Value is `Array<Record<itemSchemaId, AnswerValue>>`. The
+ *   user clicks "Add another" to add rows.
+ * - `file-upload` — like `repeater` but each row is anchored to an uploaded
+ *   File. Value is `Array<FileEntry>`. The package's renderer collects
+ *   `File` objects + per-file metadata; the actual upload-to-server
+ *   pipeline is the consumer's responsibility (the package only collects
+ *   answer state).
  */
-type QuestionInputType = 'short-text' | 'long-text' | 'select' | 'multi-select' | 'scale' | 'list';
+type QuestionInputType = 'short-text' | 'long-text' | 'single-select' | 'multi-select' | 'scale' | 'list' | 'date' | 'composite' | 'repeater' | 'file-upload';
+/**
+ * The runtime value carried by a single answer. The shape depends on the
+ * question's `inputType`:
+ *
+ * | inputType        | Value shape                            |
+ * | ---------------- | -------------------------------------- |
+ * | short-text       | `string`                               |
+ * | long-text        | `string`                               |
+ * | single-select    | `string` (the selected option's value) |
+ * | multi-select     | `string[]`                             |
+ * | scale            | `string` (numeric string)              |
+ * | list             | `string[]`                             |
+ * | date             | `string` (ISO 8601 date)               |
+ * | composite        | `AnswerComposite`                      |
+ * | repeater         | `AnswerRepeater`                       |
+ * | file-upload      | `AnswerFileUpload`                     |
+ *
+ * `undefined` is used to mean "not yet answered."
+ */
+type AnswerValue = string | string[] | AnswerComposite | AnswerRepeater | AnswerFileUpload | undefined;
+/** Composite answer: a record keyed by sub-question id. */
+type AnswerComposite = {
+    [subQuestionId: string]: AnswerValue;
+};
+/** Repeater answer: an array of records, each keyed by itemSchema sub-question id. */
+type AnswerRepeater = Array<{
+    [itemSchemaId: string]: AnswerValue;
+}>;
+/**
+ * A single uploaded file entry for `file-upload` questions.
+ *
+ * - At interview time, `file` is a browser `File` object (from drag-and-drop
+ *   or `<input type="file">`).
+ * - After the consumer uploads it (out-of-band), `file` may be replaced with
+ *   a server-assigned descriptor (e.g., `{ name, path, size }`). The
+ *   package treats anything matching the descriptor shape as "uploaded".
+ * - `metadata` carries per-file answers conforming to the question's
+ *   `itemSchema` (e.g., title, author, description).
+ */
+type FileEntry = {
+    file: File | {
+        name: string;
+        size: number;
+        path?: string;
+        type?: string;
+    };
+    metadata: {
+        [itemSchemaId: string]: AnswerValue;
+    };
+};
+type AnswerFileUpload = FileEntry[];
 /**
  * A single question in an interview flow. Consumers provide an array of
  * these to drive the engine.
  *
- * The `generates` field is consumer-specific metadata (e.g.,
- * "wiki/overview.md intro" or "CLAUDE.md project description") — the engine
- * doesn't interpret it; it's preserved through the answer collection pipeline
- * for the consumer's downstream generators (e.g., `@dataimago/onboarding-engine`).
+ * Field availability by `inputType`:
+ *
+ * | Field           | Required for                                  |
+ * | --------------- | --------------------------------------------- |
+ * | options         | single-select, multi-select, scale            |
+ * | listRange       | list (optional bounds)                        |
+ * | subQuestions    | composite (the inline sub-question fields)    |
+ * | itemSchema      | repeater + file-upload (per-row sub-questions)|
  */
 interface InterviewQuestion {
     /** Stable unique identifier; used as the answer-record key. */
@@ -69,7 +139,7 @@ interface InterviewQuestion {
     examples?: string[];
     /** Which input shape to render. */
     inputType: QuestionInputType;
-    /** Required for select / multi-select / scale; ignored for other types. */
+    /** Required for single-select / multi-select / scale; ignored otherwise. */
     options?: Array<{
         value: string;
         label: string;
@@ -90,17 +160,34 @@ interface InterviewQuestion {
         min: number;
         max: number;
     };
+    /**
+     * Composite-only: the fixed set of sub-questions that get answered as part
+     * of this composite question. Their answers land at
+     * `answers[parentId][subQuestionId]`.
+     */
+    subQuestions?: InterviewQuestion[];
+    /**
+     * Repeater + file-upload: the per-row sub-question schema. Each row of the
+     * answer array is `Record<itemSchemaId, AnswerValue>`.
+     */
+    itemSchema?: InterviewQuestion[];
 }
 /**
- * The runtime answer record. Keys are `InterviewQuestion.id`; values are
- * either the answer string (for short-text, long-text, select, scale) or
- * an array of strings (for multi-select, list).
+ * The runtime answer record. Keys are `InterviewQuestion.id`; values
+ * conform to the per-`inputType` shape described in `AnswerValue` above.
  *
  * Consumers manage their own state container (Zustand, Redux, server-side
- * session, etc.) and pass the relevant slice into the components as props.
- * The engine is state-management-agnostic.
+ * session, useState, etc.) and pass the relevant slice into the components
+ * as props. The engine is state-management-agnostic.
+ *
+ * Consumers may narrow this to their domain-specific answer shape (e.g.,
+ * `dissertation-ai/apps/hub/src/lib/interview/answers.ts` defines a strict
+ * typed `InterviewAnswers`). This package's type is the loose lowest
+ * common denominator.
  */
-type InterviewAnswers = Record<string, string | string[]>;
+type InterviewAnswers = {
+    [questionId: string]: AnswerValue;
+};
 
 interface Props$2 {
     question: InterviewQuestion;
@@ -109,14 +196,13 @@ interface Props$2 {
      * state container). The component initializes its local form state
      * from this value and re-syncs when the question id changes.
      */
-    existingAnswer?: string | string[];
+    existingAnswer?: AnswerValue;
     /**
-     * Called when the user submits a non-empty answer (or any answer if
-     * the question is `required: false`). The consumer is expected to
+     * Called when the user submits an answer. The consumer is expected to
      * persist the answer into its state container and then advance via
      * `onNext`.
      */
-    onAnswerSubmit: (questionId: string, value: string | string[]) => void;
+    onAnswerSubmit: (questionId: string, value: AnswerValue) => void;
     /** Called after `onAnswerSubmit` to advance to the next question. */
     onNext: () => void;
     /** Called when the user clicks the Back button. */
@@ -126,34 +212,17 @@ interface Props$2 {
 }
 /**
  * Single question renderer. Handles all input types: short-text, long-text,
- * select, multi-select, scale, list. Keyboard-navigable and screen-reader
- * safe.
+ * single-select, multi-select, scale, list, date, composite, repeater,
+ * file-upload. Keyboard-navigable and screen-reader safe.
  *
- * **Decoupled from any state-management library.** The original
- * apps/hub implementation imported `useInterviewStore` directly; this
- * extracted version receives the existing answer + change handler as
- * props, leaving the consumer free to use Zustand, Redux, useState,
- * server-side session state, or any other approach.
+ * **Decoupled from any state-management library.** Consumers receive the
+ * existing answer + change handler as props.
  *
- * Iteration-1 visual identity (Phase B.2, 2026-05-06):
- * Form input fields use stone-50 elevated surface + stone-200 default border
- * + forest-700 focus border (interactive-primary focus indicator). Selected
+ * Iteration-1 visual identity: form input fields use stone-50 elevated
+ * surface + stone-200 default border + forest-700 focus border. Selected
  * radio/checkbox option states use forest-700 border + forest-50 background.
- * The examples disclosure has its border-l-2 frame preserved as
- * border-copper-200 — same decorative-emphasis role as HeroSection's
- * etymology box and ReviewSummary's "what happens next" callout, per
- * iteration-1 §5.2's preserved-decorative-copper governance.
- *
- * Iteration-2 role-shift (2026-05-07): copper is no longer the brand-accent
- * moral-weight scale (the brand accent moved to sky-blue accent-500 #1f618d).
- * Copper survives as the "warm decorative framing on the editorial scale" —
- * a distinct decorative palette, not subordinate to the brand accent. The
- * border-copper-200 site below continues to serve its visual role (warm
- * framing for examples-list editorial content); its semantic relationship
- * to the brand accent is now zero. See wiki/decisions/iteration-2-blue-accent.md.
- *
- * Extracted from `apps/hub/src/components/interview/QuestionCard.tsx`
- * during iteration-3-B.1 (2026-05-07). Decoupled from `useInterviewStore`.
+ * The examples disclosure has border-l-2 frame in border-copper-200 —
+ * preserved-decorative-copper role per iteration-2-blue-accent.md.
  */
 declare function QuestionCard({ question, existingAnswer, onAnswerSubmit, onNext, onBack, isFirst, isLast, }: Props$2): react_jsx_runtime.JSX.Element;
 
@@ -170,9 +239,8 @@ interface Props$1 {
  * question without losing later answers. Implements the wiki's pattern:
  * "Edit any prior answer — a sidebar shows all answered questions."
  *
- * **Decoupled from any state-management library.** The original
- * apps/hub implementation imported `useInterviewStore` directly; this
- * extracted version receives the answers + jump handler as props.
+ * **Decoupled from any state-management library.** Consumers receive the
+ * answers + jump handler as props.
  *
  * Iteration-1 visual identity (Phase B.2, 2026-05-06):
  * Three item states with distinct token tiers:
@@ -180,8 +248,9 @@ interface Props$1 {
  *  - answered     → stone-200 border + stone-50 bg (default, hover stone-400)
  *  - unanswered   → stone-200/50 + stone-50/50 (muted via opacity preservation)
  *
- * Extracted from `apps/hub/src/components/interview/AnswerSidebar.tsx`
- * during iteration-3-B.1 (2026-05-07). Decoupled from `useInterviewStore`.
+ * D.2.1.b extension: previews for composite/repeater/file-upload answers
+ * delegated to `summarize.ts` so all eight scalar + three compound types
+ * render consistently.
  */
 declare function AnswerSidebar({ questions, currentIndex, answers, onSelectQuestion }: Props$1): react_jsx_runtime.JSX.Element;
 
@@ -198,28 +267,37 @@ interface Props {
  * Shows all answers so the user can confirm ownership of the output before
  * committing.
  *
- * **Decoupled from any state-management library.** The original
- * apps/hub implementation imported `useInterviewStore` directly; this
- * extracted version receives the answer record as a prop.
+ * **Decoupled from any state-management library.** Consumers receive the
+ * answer record as a prop.
  *
  * Iteration-1 visual identity (Phase B.2, 2026-05-06):
  * Editorial Josefin display family on the heading and the "What happens next"
  * callout title. Stone-tier surfaces and content text throughout. The
  * "What happens next" callout box preserves border-copper-300 + bg-copper-50 —
- * iteration-1 §5.2's preserved-decorative-copper role applied to the
- * informational/forward-looking callout, same pattern as HeroSection's
- * etymology box.
- *
- * Iteration-2 role-shift (2026-05-07): copper is no longer subordinate to
- * the brand accent (which moved to sky-blue accent-500 #1f618d). Copper is
- * its own "warm decorative framing on the editorial scale" — distinct from
- * the brand-accent role. The "What happens next" callout continues to serve
- * its visual function (warm forward-looking framing); its semantic relation
- * to the brand accent is now zero. See wiki/decisions/iteration-2-blue-accent.md.
- *
- * Extracted from `apps/hub/src/components/interview/ReviewSummary.tsx`
- * during iteration-3-B.1 (2026-05-07). Decoupled from `useInterviewStore`.
+ * preserved-decorative-copper role per iteration-2-blue-accent.md.
+ *
+ * D.2.1.b extension: rendering of composite/repeater/file-upload answers
+ * delegated to `summarize.ts` so all answer types display consistently.
  */
 declare function ReviewSummary({ questions, answers, onGenerate, onEdit, generating }: Props): react_jsx_runtime.JSX.Element;
 
-export { AnswerSidebar, type InterviewAnswers, type InterviewQuestion, ProgressBar, QuestionCard, type QuestionInputType, ReviewSummary };
+/**
+ * Helpers for rendering one-line / summary previews of answer values in
+ * `AnswerSidebar` and `ReviewSummary`. Centralized so the two components
+ * stay consistent when new answer shapes are added.
+ */
+
+declare function isAnswered(value: AnswerValue): boolean;
+/**
+ * A short, single-line preview suitable for sidebar items. Truncates
+ * long content. Returns the empty string for unanswered values.
+ */
+declare function summarizeShort(question: InterviewQuestion, value: AnswerValue, maxLen?: number): string;
+/**
+ * A richer multi-line summary suitable for the ReviewSummary list. May
+ * contain newlines; consumers should render in a `whitespace-pre-wrap`
+ * container.
+ */
+declare function summarizeLong(question: InterviewQuestion, value: AnswerValue): string;
+
+export { type AnswerComposite, type AnswerFileUpload, type AnswerRepeater, AnswerSidebar, type AnswerValue, type FileEntry, type InterviewAnswers, type InterviewQuestion, ProgressBar, QuestionCard, type QuestionInputType, ReviewSummary, isAnswered, summarizeLong, summarizeShort };