@wireai/activation 0.7.0 → 0.9.0

package/src/questionnaire/steps.ts

@@ -0,0 +1,261 @@
+/**
+ * steps.ts — the pure multi-step machine behind the questionnaire popup.
+ *
+ * The gate asks ONE question per step. Skippability is per-step (`QuestionnaireStep.required`)
+ * and, after Malik's device test 2026-07-16, it is the INVERSE of what this kit shipped for a
+ * year: `opinion` (step 1) is SKIPPABLE — the old mandatory-opinion `canSend` gate is gone —
+ * and `suggestions` (the LAST step) is REQUIRED, because "i want at least something forced".
+ * The user picks WHICH thing they say; they do not get to say nothing at all.
+ *
+ * The step logic is the interesting part of the component, so it lives here as pure
+ * functions: no React, no react-native, no JSX. The gate is then a thin renderer over this
+ * state, and `steps.test.ts` can verify advance / skip / back / the required gate under
+ * node:test without mounting anything.
+ *
+ * The wire shape is NOT this module's business: it builds `QuestionnaireAnswers`, and
+ * `buildQuestionnaireSubmission` (decision.ts) still owns the POST body exactly as before.
+ *
+ * The step ORDER is the server contract's field order (opinion → improve → suggestions),
+ * so `toAnswers` can stay a plain projection and the submission never depends on how the
+ * user navigated.
+ */
+import type { QuestionnaireAnswers, QuestionnaireDefinition } from "./types";
+
+/** The three answer fields, which are also the three steps. */
+export type QuestionnaireStepKey = "opinion" | "improve" | "suggestions";
+
+/** One question, fully resolved for rendering. */
+export interface QuestionnaireStep {
+  /** The answer field this step fills. */
+  key: QuestionnaireStepKey;
+  /** The question shown to the user (tenant-configurable). */
+  label: string;
+  /** The greyed-out example inside the input. */
+  placeholder: string;
+  /**
+   * When true the step cannot be skipped and cannot be committed blank — the gate hides
+   * Skip and disables Send until there is non-whitespace text. Only `suggestions` (the
+   * last step) carries it; see `REQUIRED_STEPS`.
+   */
+  required: boolean;
+}
+
+/**
+ * Which steps are mandatory. Malik, after testing on device 2026-07-16: "The any
+ * suggestions or feedback <the last step> is mandatory, i want at least something forced."
+ *
+ * Exactly one step is forced, and it is the LAST one, which is the only placement that
+ * works: the user has already been offered two cheap ways to say something and declined
+ * them, so the mandatory box lands as "then tell us anything" rather than as a toll gate
+ * in front of a popup they never asked for. Forcing step 1 (the old behaviour) taxed the
+ * arrival; forcing step 3 taxes the exit, after the cost is sunk.
+ *
+ * ⚠️ SERVER DEPENDENCY: this is the exact INVERSE of what the live server enforces today.
+ * `POST /v1/questionnaires/{id}/responses` validates `answers.opinion` with minLength=1 and
+ * 422s an empty one. Since step 1 is now skippable, a skipped step 1 produces `opinion: ""`
+ * and the server rejects the whole body — INCLUDING the suggestions text this module just
+ * forced out of the user. The transport is fire-and-forget (it never reads the response),
+ * so that rejection is SILENT: the user sees the thank-you either way. This client is
+ * therefore correct only once the server drops `opinion`'s minLength. Do not paper over it
+ * here — no placeholder opinion, no field reordering, no client-side guard.
+ */
+export const REQUIRED_STEPS: Record<QuestionnaireStepKey, boolean> = {
+  opinion: false,
+  improve: false,
+  suggestions: true,
+};
+
+/**
+ * Fallback questions used when the tenant configures no labels.
+ *
+ * NOTE the copy change: the old defaults tagged `improve`/`suggestions` "(optional)".
+ * That was already wrong once step 1 stopped being mandatory, and it is wronger now that
+ * `suggestions` is the one REQUIRED step. Requiredness is carried by the CONTROLS — Skip
+ * is absent and Send is disabled on a required step — not by label text, which is tenant-
+ * configurable and would drift out of sync with `REQUIRED_STEPS` the moment it changed.
+ */
+export const DEFAULT_STEP_LABELS: Record<QuestionnaireStepKey, string> = {
+  opinion: "What do you think about the app?",
+  improve: "How can we improve?",
+  suggestions: "Any suggestions?",
+};
+
+/** Per-field placeholders, carried over unchanged from the single-screen form. */
+export const STEP_PLACEHOLDERS: Record<QuestionnaireStepKey, string> = {
+  opinion: "e.g. it feels fast and clear",
+  improve: "e.g. fewer steps to start",
+  suggestions: "e.g. a dark theme",
+};
+
+/** Which way the last move went — drives the slide direction (spatial consistency). */
+export type StepDirection = "forward" | "backward";
+
+/** Answers captured so far, keyed by step. A skipped step records "". */
+export type StepDrafts = Partial<Record<QuestionnaireStepKey, string>>;
+
+/** The whole machine state. Immutable: every transition returns a new object. */
+export interface QuestionnaireStepState {
+  /** Index into the step list. */
+  index: number;
+  /** What has been typed/skipped so far. */
+  drafts: StepDrafts;
+  /** Direction of the last transition, for the pane slide. */
+  direction: StepDirection;
+  /** True once the LAST step is answered or skipped — the gate submits and thanks. */
+  done: boolean;
+}
+
+/**
+ * Resolve the tenant's labels into the ordered step list. All three steps always render:
+ * the server contract is a fixed 3-field capture, not an arbitrary question builder.
+ */
+export const buildQuestionnaireSteps = (
+  questionnaire: Pick<
+    QuestionnaireDefinition,
+    "opinion_label" | "improve_label" | "suggestions_label"
+  >,
+): QuestionnaireStep[] => [
+  {
+    key: "opinion",
+    label: questionnaire.opinion_label ?? DEFAULT_STEP_LABELS.opinion,
+    placeholder: STEP_PLACEHOLDERS.opinion,
+    required: REQUIRED_STEPS.opinion,
+  },
+  {
+    key: "improve",
+    label: questionnaire.improve_label ?? DEFAULT_STEP_LABELS.improve,
+    placeholder: STEP_PLACEHOLDERS.improve,
+    required: REQUIRED_STEPS.improve,
+  },
+  {
+    key: "suggestions",
+    label: questionnaire.suggestions_label ?? DEFAULT_STEP_LABELS.suggestions,
+    placeholder: STEP_PLACEHOLDERS.suggestions,
+    required: REQUIRED_STEPS.suggestions,
+  },
+];
+
+/** The starting state: first question, nothing answered. */
+export const initialStepState = (): QuestionnaireStepState => ({
+  index: 0,
+  drafts: {},
+  direction: "forward",
+  done: false,
+});
+
+/** The step currently on screen, or undefined once the list is exhausted. */
+export const currentStep = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+): QuestionnaireStep | undefined => steps[state.index];
+
+/** Whether `index` is the final step (the one whose commit submits). */
+export const isLastStep = (steps: readonly QuestionnaireStep[], index: number): boolean =>
+  index >= steps.length - 1;
+
+/** Back navigation is available on every step except the first. */
+export const canGoBack = (state: QuestionnaireStepState): boolean => state.index > 0;
+
+/**
+ * Whether the step on screen may be skipped — false on a required step, which is how the
+ * gate knows to render no Skip control at all rather than a Skip that silently does nothing.
+ */
+export const canSkipStep = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+): boolean => !(steps[state.index]?.required ?? false);
+
+/**
+ * Whether `value` satisfies the step on screen — i.e. whether committing it will actually
+ * move. Optional steps accept anything (including ""); a required step needs non-whitespace
+ * text, because "   " is not "at least something". The gate reads this to disable Send.
+ *
+ * The SAME predicate `commitStep` enforces, so a disabled Send and a refused commit can
+ * never disagree about what counts as answered.
+ */
+export const canCommitStep = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+  value: string,
+): boolean => {
+  const step = steps[state.index];
+  if (!step) return false;
+  return !step.required || value.trim().length > 0;
+};
+
+/**
+ * Record `value` for the CURRENT step WITHOUT navigating.
+ *
+ * This is the shared "the text on screen is now part of the answers" primitive: `commitStep`
+ * is exactly this plus the forward move, and the gate's Back does this before `goBack`. It
+ * exists because the gate's inputs are UNCONTROLLED, so the step on screen holds its text
+ * only in the component's draft ref until something folds it in here — meaning EVERY way of
+ * leaving a step has to stash first or the text is silently destroyed.
+ */
+export const stashDraft = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+  value: string,
+): QuestionnaireStepState => {
+  const step = steps[state.index];
+  if (!step) return state;
+  return { ...state, drafts: { ...state.drafts, [step.key]: value } };
+};
+
+/**
+ * Record `value` for the CURRENT step and move on. On the last step this sets `done`
+ * (the gate reads that as "submit now") and leaves the index parked, so `toAnswers` is
+ * called with every draft present.
+ *
+ * A required step refuses a blank `value` and returns the state UNCHANGED. That is the
+ * single enforcement point for the mandatory last step: `skipStep` is defined as committing
+ * "", so it becomes a no-op there for free, and the gate's disabled Send is belt-and-braces
+ * over a machine that already cannot be walked past.
+ */
+export const commitStep = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+  value: string,
+): QuestionnaireStepState => {
+  const step = steps[state.index];
+  if (!step) return state;
+  if (!canCommitStep(steps, state, value)) return state;
+  const { drafts } = stashDraft(steps, state, value);
+  const last = isLastStep(steps, state.index);
+  return {
+    index: last ? state.index : state.index + 1,
+    drafts,
+    direction: "forward",
+    done: last,
+  };
+};
+
+/**
+ * Skip the current step. Deliberately the SAME transition as answering with nothing —
+ * "skipped" and "left blank" are one concept, so there is one code path and no way for
+ * the two to drift. On a REQUIRED step that identity is what makes skipping impossible:
+ * committing "" is refused, so this returns the state unchanged.
+ */
+export const skipStep = (
+  steps: readonly QuestionnaireStep[],
+  state: QuestionnaireStepState,
+): QuestionnaireStepState => commitStep(steps, state, "");
+
+/** Go back one step, keeping every draft so the user's earlier text is still there. */
+export const goBack = (state: QuestionnaireStepState): QuestionnaireStepState =>
+  state.index <= 0 ? state : { ...state, index: state.index - 1, direction: "backward" };
+
+/**
+ * Project the drafts onto the answers contract. Missing/skipped steps become "" — the
+ * exact input `buildQuestionnaireSubmission` already expects, which trims and maps the
+ * two optional fields to null. The wire shape is unchanged by the multi-step rework.
+ *
+ * `opinion` can now legitimately be "" (step 1 is skippable), which the live server still
+ * rejects with a 422 — see the REQUIRED_STEPS note above. That is a server fix, not a
+ * reason to fabricate a value here.
+ */
+export const toAnswers = (drafts: StepDrafts): QuestionnaireAnswers => ({
+  opinion: drafts.opinion ?? "",
+  improve: drafts.improve ?? "",
+  suggestions: drafts.suggestions ?? "",
+});

package/src/questionnaire/types.ts

@@ -1,9 +1,11 @@
 /**
  * Shared types for the questionnaire module (the skippable pre-onboarding popup).
  *
- * The gate asks a short set of questions in a centered popup: ONE mandatory free-text
- * "what do you think about the app" (the opinion), plus two OPTIONAL boxes ("help us
- * improve" + "suggestions"). WHEN the gate shows is decided by local rules OR a
+ * The gate asks a short set of questions in a centered popup, ONE per step: a SKIPPABLE
+ * "what do you think about the app" (the opinion), a SKIPPABLE "help us improve", and a
+ * REQUIRED "suggestions" as the last step (Malik 2026-07-16: "i want at least something
+ * forced"). Which step is forced lives in `steps.ts` (`REQUIRED_STEPS`), not here.
+ * WHEN the gate shows is decided by local rules OR a
  * server-provided decision (the AI seam), gated by the `questionnaire` master switch and
  * shown at most once per user per questionnaire `id`. Dependency-free type surface.
  */
@@ -30,13 +32,19 @@ export interface QuestionnaireDecision {
 export interface QuestionnaireDefinition {
   /** Gate key. Seen/last-shown/session keys derive from it (`wire_questionnaire_<id>_*`). */
   id: string;
-  /** Popup heading. Defaults to a neutral prompt when absent. */
+  /**
+   * @deprecated NOT RENDERED since 2026-07-16. The gate is one-question-per-step, so each
+   * step's own question is its heading; a title above it was a second asking-text, repeated
+   * on all three steps and briefly drawn twice mid-slide. Malik cut it on device. The field
+   * stays in the type because tenants still send it and the server contract is unchanged —
+   * dropping it from the wire is a separate, server-side decision.
+   */
   title?: string;
-  /** Label for the MANDATORY opinion box ("what do you think about the app"). */
+  /** Label for the SKIPPABLE opinion step ("what do you think about the app"). */
   opinion_label?: string;
-  /** Label for the first OPTIONAL box ("help us improve"). */
+  /** Label for the SKIPPABLE "help us improve" step. */
   improve_label?: string;
-  /** Label for the second OPTIONAL box ("suggestions"). */
+  /** Label for the REQUIRED "suggestions" step — the one answer the user cannot skip. */
   suggestions_label?: string;
 
   // ── Local fallback firing rules (used only when no server decision is passed) ──
@@ -59,13 +67,20 @@ export interface QuestionnaireDefinition {
   timeoutFallbackMs?: number | null;
 }
 
-/** The user's three answers. `opinion` is the only mandatory one. */
+/**
+ * The user's three answers.
+ *
+ * ⚠️ `opinion` is TYPED as always-present because the wire shape says so, but since
+ * 2026-07-16 its step is skippable, so "" is a legitimate value. The live server still
+ * validates it with minLength=1 and 422s an empty one — a server-side fix this client
+ * depends on. See the REQUIRED_STEPS note in steps.ts.
+ */
 export interface QuestionnaireAnswers {
-  /** The mandatory "what do you think about the app" free text. */
+  /** The "what do you think about the app" free text. Skippable → may be "". */
   opinion: string;
-  /** The optional "help us improve" free text. */
+  /** The "help us improve" free text. Skippable → may be "" / absent. */
   improve?: string;
-  /** The optional "suggestions" free text. */
+  /** The "any improvements or feedback" free text. REQUIRED of the user in the gate. */
   suggestions?: string;
 }
 
@@ -140,7 +155,13 @@ export interface QuestionnaireGateProps {
   onShown?: () => void;
   /** Partial theme merged over the active onboarding theme. */
   theme?: Partial<import("../theme/types").OnboardingTheme>;
-  /** Show a Skip/Not now control. Default true (always skippable, never a dead end). */
+  /**
+   * Whether the WHOLE popup can be dismissed — backdrop tap and Android hardware back.
+   * Default true (never a dead end), and the only escape from the required last step, so
+   * turning it off traps a user who has nothing to say. That path is what fires
+   * `questionnaire_dismissed`; the in-card "Not now" link it used to name is gone.
+   * Per-step Skip is separate and is driven by `steps.ts`, not by this flag.
+   */
   dismissible?: boolean;
 }