@wireai/activation 0.8.0 → 0.9.0

package/dist/questionnaire/index.d.mts

@@ -1,9 +1,9 @@
 import React__default from 'react';
 import { O as OnboardingTheme } from '../types-BKfpdZzX.mjs';
-import { C as CoachmarkStorage } from '../types-GL_hQ0TN.mjs';
-import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CMuOexw0.mjs';
-export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-BzbiKwk3.mjs';
-import '../types-A6pTxIZV.mjs';
+import { C as CoachmarkStorage } from '../types-BcmagF6K.mjs';
+import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CKFhyrMu.mjs';
+export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-Bl_M2y3r.mjs';
+import '../types-CNUqMK0D.mjs';
 
 /**
  * The firing verdict - the SAME contract on both sides of the seam. `decideQuestionnaire`
@@ -24,13 +24,19 @@ interface QuestionnaireDecision {
 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;
     /** Master local switch. Default true. */
     enabled?: boolean;
@@ -50,13 +56,20 @@ 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.
+ */
 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;
 }
 /** Non-PII correlation extras sent with a submission (the `meta` bucket in the POST body). */
@@ -121,7 +134,13 @@ interface QuestionnaireGateProps {
     onShown?: () => void;
     /** Partial theme merged over the active onboarding theme. */
     theme?: Partial<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;
 }
 /** Options for `useQuestionnaireGate` - the WHEN decision. */
@@ -161,15 +180,40 @@ interface QuestionnaireGateController {
 }
 
 /**
- * QuestionnaireGate - the skippable pre-onboarding questionnaire popup.
+ * QuestionnaireGate - the multi-step questionnaire popup.
+ *
+ * ONE question per step. Steps 1-2 are skippable; the LAST step is REQUIRED (Malik's
+ * device test 2026-07-16: "i want at least something forced"). The user chooses which
+ * thing they tell us, not whether they tell us anything. `steps.ts` owns that rule and
+ * every transition as pure functions, unit-tested under node:test without mounting React;
+ * this component is a thin renderer over that machine.
+ *
+ * The CHROME (back icon + step dots) is a static header, deliberately NOT part of the
+ * sliding pane - see the four notes below. Only the question, its box and its controls move.
+ *
+ *  - No title. The gate used to render `questionnaire.title` as a heading ON EVERY STEP,
+ *    directly above the step's own question. Two asking-texts stacked, one of them the same
+ *    string three times, and mid-slide the outgoing and incoming panes each drew their own
+ *    copy so it was briefly on screen TWICE. Malik saw it on the last step, where the
+ *    forced question most needs the focus. The question IS the heading now; it renders once.
+ *  - No "Question 2 of 3" counter. `StepDots` says it without spending a line next to the
+ *    question, which is what the user is supposed to be reading.
+ *  - Back is a top-left icon, not a link in the button stack, and it is simply absent on
+ *    step 1 rather than present-but-dead.
+ *  - No "Not now". Per-step Skip is the only in-card opt-out. `questionnaire_dismissed`
+ *    moved to the modal's dismiss path (backdrop tap / Android back) - see `handleDismissed`.
+ *
+ * The wire shape is UNCHANGED. `buildQuestionnaireSubmission` still builds the exact same
+ * `POST /v1/questionnaires/{id}/responses` body from the same three answers; a skipped
+ * step is simply an empty answer, which is what the builder already handled.
+ *
+ * ⚠️ This gate now REQUIRES the server to accept an empty `answers.opinion` - step 1 is
+ * skippable and the live endpoint still 422s a blank opinion, silently (the transport is
+ * fire-and-forget). See the REQUIRED_STEPS note in steps.ts. Server fix, not a client one.
  *
- * A centered popup (over the shared `CenteredModal` shell) with three inputs:
- *   • a MANDATORY multiline "what do you think about the app" box (~4 lines), and
- *   • two OPTIONAL smaller boxes ("help us improve" + "suggestions").
- * Send is disabled ONLY until the opinion box has text; the two optional boxes never gate it.
- * The gate is ALWAYS skippable (a "Not now"/"Skip" link plays the popup exit), so it is never
- * a dead end. On send it builds the contract body and fire-and-forgets it to the Wire server,
- * then shows a warm thank-you until the user taps the backdrop to close.
+ * Motion: `ModalPaneHost` slides step→step (and mirrors the slide on Back) and resizes the
+ * card; `StepDots` fills; `DoneCheck` plays the submit payoff. All shared, all reduce-motion
+ * aware. Haptics are lazy + optional (`haptics/haptics.ts`) and silently absent otherwise.
  *
  * The form NEVER asks for identity (no name / email / contact field): the host already
  * identifies the user via `sessionId` + `meta` (user_id, device_key, session_count), which is
@@ -187,8 +231,10 @@ declare const useQuestionnaireGate: ({ config: configProp, decision: decisionPro
  */
 declare const decideQuestionnaire: (local: QuestionnaireDecision, decision?: QuestionnaireDecision) => QuestionnaireDecision;
 /**
- * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is the only mandatory
- * answer (trimmed); `improve`/`suggestions` are trimmed and sent as `null` when empty. The
+ * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is always sent as a
+ * string (trimmed, possibly "" now that its step is skippable — the live server still
+ * rejects that, see steps.ts REQUIRED_STEPS); `improve`/`suggestions` are trimmed and sent
+ * as `null` when empty. The
  * `meta` bucket carries the non-PII correlation fields (user_id / device_key / session_count),
  * each defaulting to null. Free text lives ONLY here, never in analytics events.
  */

package/dist/questionnaire/index.d.ts

@@ -1,9 +1,9 @@
 import React__default from 'react';
 import { O as OnboardingTheme } from '../types-BKfpdZzX.js';
-import { C as CoachmarkStorage } from '../types-GL_hQ0TN.js';
-import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CMuOexw0.js';
-export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-plDEOCkt.js';
-import '../types-BhpXJGlg.js';
+import { C as CoachmarkStorage } from '../types-BcmagF6K.js';
+import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CKFhyrMu.js';
+export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-Cau5KmP6.js';
+import '../types-Buj9Lw9t.js';
 
 /**
  * The firing verdict - the SAME contract on both sides of the seam. `decideQuestionnaire`
@@ -24,13 +24,19 @@ interface QuestionnaireDecision {
 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;
     /** Master local switch. Default true. */
     enabled?: boolean;
@@ -50,13 +56,20 @@ 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.
+ */
 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;
 }
 /** Non-PII correlation extras sent with a submission (the `meta` bucket in the POST body). */
@@ -121,7 +134,13 @@ interface QuestionnaireGateProps {
     onShown?: () => void;
     /** Partial theme merged over the active onboarding theme. */
     theme?: Partial<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;
 }
 /** Options for `useQuestionnaireGate` - the WHEN decision. */
@@ -161,15 +180,40 @@ interface QuestionnaireGateController {
 }
 
 /**
- * QuestionnaireGate - the skippable pre-onboarding questionnaire popup.
+ * QuestionnaireGate - the multi-step questionnaire popup.
+ *
+ * ONE question per step. Steps 1-2 are skippable; the LAST step is REQUIRED (Malik's
+ * device test 2026-07-16: "i want at least something forced"). The user chooses which
+ * thing they tell us, not whether they tell us anything. `steps.ts` owns that rule and
+ * every transition as pure functions, unit-tested under node:test without mounting React;
+ * this component is a thin renderer over that machine.
+ *
+ * The CHROME (back icon + step dots) is a static header, deliberately NOT part of the
+ * sliding pane - see the four notes below. Only the question, its box and its controls move.
+ *
+ *  - No title. The gate used to render `questionnaire.title` as a heading ON EVERY STEP,
+ *    directly above the step's own question. Two asking-texts stacked, one of them the same
+ *    string three times, and mid-slide the outgoing and incoming panes each drew their own
+ *    copy so it was briefly on screen TWICE. Malik saw it on the last step, where the
+ *    forced question most needs the focus. The question IS the heading now; it renders once.
+ *  - No "Question 2 of 3" counter. `StepDots` says it without spending a line next to the
+ *    question, which is what the user is supposed to be reading.
+ *  - Back is a top-left icon, not a link in the button stack, and it is simply absent on
+ *    step 1 rather than present-but-dead.
+ *  - No "Not now". Per-step Skip is the only in-card opt-out. `questionnaire_dismissed`
+ *    moved to the modal's dismiss path (backdrop tap / Android back) - see `handleDismissed`.
+ *
+ * The wire shape is UNCHANGED. `buildQuestionnaireSubmission` still builds the exact same
+ * `POST /v1/questionnaires/{id}/responses` body from the same three answers; a skipped
+ * step is simply an empty answer, which is what the builder already handled.
+ *
+ * ⚠️ This gate now REQUIRES the server to accept an empty `answers.opinion` - step 1 is
+ * skippable and the live endpoint still 422s a blank opinion, silently (the transport is
+ * fire-and-forget). See the REQUIRED_STEPS note in steps.ts. Server fix, not a client one.
  *
- * A centered popup (over the shared `CenteredModal` shell) with three inputs:
- *   • a MANDATORY multiline "what do you think about the app" box (~4 lines), and
- *   • two OPTIONAL smaller boxes ("help us improve" + "suggestions").
- * Send is disabled ONLY until the opinion box has text; the two optional boxes never gate it.
- * The gate is ALWAYS skippable (a "Not now"/"Skip" link plays the popup exit), so it is never
- * a dead end. On send it builds the contract body and fire-and-forgets it to the Wire server,
- * then shows a warm thank-you until the user taps the backdrop to close.
+ * Motion: `ModalPaneHost` slides step→step (and mirrors the slide on Back) and resizes the
+ * card; `StepDots` fills; `DoneCheck` plays the submit payoff. All shared, all reduce-motion
+ * aware. Haptics are lazy + optional (`haptics/haptics.ts`) and silently absent otherwise.
  *
  * The form NEVER asks for identity (no name / email / contact field): the host already
  * identifies the user via `sessionId` + `meta` (user_id, device_key, session_count), which is
@@ -187,8 +231,10 @@ declare const useQuestionnaireGate: ({ config: configProp, decision: decisionPro
  */
 declare const decideQuestionnaire: (local: QuestionnaireDecision, decision?: QuestionnaireDecision) => QuestionnaireDecision;
 /**
- * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is the only mandatory
- * answer (trimmed); `improve`/`suggestions` are trimmed and sent as `null` when empty. The
+ * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is always sent as a
+ * string (trimmed, possibly "" now that its step is skippable — the live server still
+ * rejects that, see steps.ts REQUIRED_STEPS); `improve`/`suggestions` are trimmed and sent
+ * as `null` when empty. The
  * `meta` bucket carries the non-PII correlation fields (user_id / device_key / session_count),
  * each defaulting to null. Free text lives ONLY here, never in analytics events.
  */