@dataimago/interview 0.2.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,225 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface Props$3 {
+    current: number;
+    total: number;
+    estimatedMinutesRemaining: number;
+}
+/**
+ * Linear progress indicator for the interview flow. Renders the
+ * "Question N of M" caption, the estimated minutes remaining, and a
+ * forest-700 fill bar at `(current / total) * 100%`.
+ *
+ * Iteration-1 visual identity (Phase B.2, 2026-05-06):
+ * stone-100 surface with stone-200 border; forest-700 fill bar; stone-700
+ * caption text. Pure-render component — no state-management dependency.
+ *
+ * Extracted from `apps/hub/src/components/interview/ProgressBar.tsx`
+ * during iteration-3-B.1 (2026-05-07). No prop API change.
+ */
+declare function ProgressBar({ current, total, estimatedMinutesRemaining }: Props$3): react_jsx_runtime.JSX.Element;
+
+/**
+ * @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.
+ *
+ * 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).
+ *
+ * Design authority: `dataimago-design/wiki/patterns/onboarding-interview.md`.
+ */
+/**
+ * The set of input shapes the interview engine knows how to render.
+ *
+ * - `short-text` — single-line text field
+ * - `long-text` — multi-line textarea
+ * - `select` — single-choice radio group with `options[]`
+ * - `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)
+ * - `list` — variable-length list of short-text items, bounded by `listRange`
+ */
+type QuestionInputType = 'short-text' | 'long-text' | 'select' | 'multi-select' | 'scale' | 'list';
+/**
+ * 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`).
+ */
+interface InterviewQuestion {
+    /** Stable unique identifier; used as the answer-record key. */
+    id: string;
+    /** Render order (1-based, ascending). */
+    order: number;
+    /** The primary question prompt. */
+    prompt: string;
+    /** Optional secondary explanation shown below the prompt. */
+    subprompt?: string;
+    /** Optional concrete examples shown in a disclosure under the prompt. */
+    examples?: string[];
+    /** Which input shape to render. */
+    inputType: QuestionInputType;
+    /** Required for select / multi-select / scale; ignored for other types. */
+    options?: Array<{
+        value: string;
+        label: string;
+        description?: string;
+    }>;
+    /** Whether the consumer can advance without an answer. */
+    required: boolean;
+    /** Optional explanation shown when the user attempts to skip. */
+    skipConsequence?: string;
+    /**
+     * Consumer-specific metadata: which downstream artifacts (wiki pages,
+     * template placeholders) this answer populates. Engine-opaque; preserved
+     * through to the consumer's generator pipeline.
+     */
+    generates: string[];
+    /** Min/max items for `inputType: 'list'` questions; ignored otherwise. */
+    listRange?: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * 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).
+ *
+ * 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.
+ */
+type InterviewAnswers = Record<string, string | string[]>;
+
+interface Props$2 {
+    question: InterviewQuestion;
+    /**
+     * The currently-saved answer for this question (from the consumer's
+     * state container). The component initializes its local form state
+     * from this value and re-syncs when the question id changes.
+     */
+    existingAnswer?: string | string[];
+    /**
+     * Called when the user submits a non-empty answer (or any answer if
+     * the question is `required: false`). The consumer is expected to
+     * persist the answer into its state container and then advance via
+     * `onNext`.
+     */
+    onAnswerSubmit: (questionId: string, value: string | string[]) => void;
+    /** Called after `onAnswerSubmit` to advance to the next question. */
+    onNext: () => void;
+    /** Called when the user clicks the Back button. */
+    onBack: () => void;
+    isFirst: boolean;
+    isLast: boolean;
+}
+/**
+ * Single question renderer. Handles all input types: short-text, long-text,
+ * select, multi-select, scale, list. 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.
+ *
+ * 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
+ * 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`.
+ */
+declare function QuestionCard({ question, existingAnswer, onAnswerSubmit, onNext, onBack, isFirst, isLast, }: Props$2): react_jsx_runtime.JSX.Element;
+
+interface Props$1 {
+    questions: InterviewQuestion[];
+    currentIndex: number;
+    /** Consumer's current answer record (read-only — engine doesn't write). */
+    answers: InterviewAnswers;
+    /** Called when the user clicks a sidebar item to jump to that question. */
+    onSelectQuestion: (index: number) => void;
+}
+/**
+ * Sidebar showing all answered questions. Clicking any returns to edit that
+ * 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.
+ *
+ * Iteration-1 visual identity (Phase B.2, 2026-05-06):
+ * Three item states with distinct token tiers:
+ *  - current      → forest-700 border + forest-50 bg (interactive primary)
+ *  - 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`.
+ */
+declare function AnswerSidebar({ questions, currentIndex, answers, onSelectQuestion }: Props$1): react_jsx_runtime.JSX.Element;
+
+interface Props {
+    questions: InterviewQuestion[];
+    /** Consumer's current answer record (read-only — engine doesn't write). */
+    answers: InterviewAnswers;
+    onGenerate: () => void;
+    onEdit: (questionIndex: number) => void;
+    generating: boolean;
+}
+/**
+ * Final review screen — the penultimate step before generation.
+ * 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.
+ *
+ * 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`.
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface Props$3 {
+    current: number;
+    total: number;
+    estimatedMinutesRemaining: number;
+}
+/**
+ * Linear progress indicator for the interview flow. Renders the
+ * "Question N of M" caption, the estimated minutes remaining, and a
+ * forest-700 fill bar at `(current / total) * 100%`.
+ *
+ * Iteration-1 visual identity (Phase B.2, 2026-05-06):
+ * stone-100 surface with stone-200 border; forest-700 fill bar; stone-700
+ * caption text. Pure-render component — no state-management dependency.
+ *
+ * Extracted from `apps/hub/src/components/interview/ProgressBar.tsx`
+ * during iteration-3-B.1 (2026-05-07). No prop API change.
+ */
+declare function ProgressBar({ current, total, estimatedMinutesRemaining }: Props$3): react_jsx_runtime.JSX.Element;
+
+/**
+ * @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.
+ *
+ * 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).
+ *
+ * Design authority: `dataimago-design/wiki/patterns/onboarding-interview.md`.
+ */
+/**
+ * The set of input shapes the interview engine knows how to render.
+ *
+ * - `short-text` — single-line text field
+ * - `long-text` — multi-line textarea
+ * - `select` — single-choice radio group with `options[]`
+ * - `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)
+ * - `list` — variable-length list of short-text items, bounded by `listRange`
+ */
+type QuestionInputType = 'short-text' | 'long-text' | 'select' | 'multi-select' | 'scale' | 'list';
+/**
+ * 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`).
+ */
+interface InterviewQuestion {
+    /** Stable unique identifier; used as the answer-record key. */
+    id: string;
+    /** Render order (1-based, ascending). */
+    order: number;
+    /** The primary question prompt. */
+    prompt: string;
+    /** Optional secondary explanation shown below the prompt. */
+    subprompt?: string;
+    /** Optional concrete examples shown in a disclosure under the prompt. */
+    examples?: string[];
+    /** Which input shape to render. */
+    inputType: QuestionInputType;
+    /** Required for select / multi-select / scale; ignored for other types. */
+    options?: Array<{
+        value: string;
+        label: string;
+        description?: string;
+    }>;
+    /** Whether the consumer can advance without an answer. */
+    required: boolean;
+    /** Optional explanation shown when the user attempts to skip. */
+    skipConsequence?: string;
+    /**
+     * Consumer-specific metadata: which downstream artifacts (wiki pages,
+     * template placeholders) this answer populates. Engine-opaque; preserved
+     * through to the consumer's generator pipeline.
+     */
+    generates: string[];
+    /** Min/max items for `inputType: 'list'` questions; ignored otherwise. */
+    listRange?: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * 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).
+ *
+ * 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.
+ */
+type InterviewAnswers = Record<string, string | string[]>;
+
+interface Props$2 {
+    question: InterviewQuestion;
+    /**
+     * The currently-saved answer for this question (from the consumer's
+     * state container). The component initializes its local form state
+     * from this value and re-syncs when the question id changes.
+     */
+    existingAnswer?: string | string[];
+    /**
+     * Called when the user submits a non-empty answer (or any answer if
+     * the question is `required: false`). The consumer is expected to
+     * persist the answer into its state container and then advance via
+     * `onNext`.
+     */
+    onAnswerSubmit: (questionId: string, value: string | string[]) => void;
+    /** Called after `onAnswerSubmit` to advance to the next question. */
+    onNext: () => void;
+    /** Called when the user clicks the Back button. */
+    onBack: () => void;
+    isFirst: boolean;
+    isLast: boolean;
+}
+/**
+ * Single question renderer. Handles all input types: short-text, long-text,
+ * select, multi-select, scale, list. 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.
+ *
+ * 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
+ * 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`.
+ */
+declare function QuestionCard({ question, existingAnswer, onAnswerSubmit, onNext, onBack, isFirst, isLast, }: Props$2): react_jsx_runtime.JSX.Element;
+
+interface Props$1 {
+    questions: InterviewQuestion[];
+    currentIndex: number;
+    /** Consumer's current answer record (read-only — engine doesn't write). */
+    answers: InterviewAnswers;
+    /** Called when the user clicks a sidebar item to jump to that question. */
+    onSelectQuestion: (index: number) => void;
+}
+/**
+ * Sidebar showing all answered questions. Clicking any returns to edit that
+ * 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.
+ *
+ * Iteration-1 visual identity (Phase B.2, 2026-05-06):
+ * Three item states with distinct token tiers:
+ *  - current      → forest-700 border + forest-50 bg (interactive primary)
+ *  - 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`.
+ */
+declare function AnswerSidebar({ questions, currentIndex, answers, onSelectQuestion }: Props$1): react_jsx_runtime.JSX.Element;
+
+interface Props {
+    questions: InterviewQuestion[];
+    /** Consumer's current answer record (read-only — engine doesn't write). */
+    answers: InterviewAnswers;
+    onGenerate: () => void;
+    onEdit: (questionIndex: number) => void;
+    generating: boolean;
+}
+/**
+ * Final review screen — the penultimate step before generation.
+ * 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.
+ *
+ * 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`.
+ */
+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 };