WEBDEV-7680 Add feedback survey component to present & handle multiple questions (#5)

* Add feedback survey component

* Upgrade dependencies to get tests running

* Add unit tests for new features

* Add missing logic & tests for comment box styles

* Switch from updated to willUpdate to avoid needless cycles

* Add further unit tests for the feedback survey

* Rename some vars

* Update naming & exports

* Ensure prompts fill max width

* Update background color

* Send 'rating' instead of 'vote', improve docs

* Refactor for much greater extensibility

* Reflect extra properties

* Remove some unused types

* Add focus traps, aria roles, and labels where necessary

* Remove unneeded async from method

* Correct outdated doc comment

* Use ia-styles for button styling

* Update README with information about the new survey features

* Switch from CSS-based numbering to slotted text to satisfy Safari

* Clean up template a bit for readability

* Fix focus method to find the first focusable slotted child

* Slightly simplify focusable condition

Author: latonv

README.md

@@ -2,7 +2,7 @@
 
 # Internet Archive Feature Feedback Component
 
-This is a widget that lets us collect feedback on features that we release. Written in LitElement.
+This is a collection of widgets that let us collect feedback on features that we release. Written in LitElement.
 
 ![Feature Feedback](/assets/screenshot.png "Screenshot")
 
@@ -15,6 +15,8 @@ This is a widget that lets us collect feedback on features that we release. Writ
 
 ## Usage
 
+### Feature Feedback widget for single-question feedback
+
 ```ts
 import { RecaptchaManager } from '@internetarchive/recaptcha-manager';
 import { SharedResizeObserver } from '@internetarchive/shared-resize-observer';
@@ -39,6 +41,91 @@ html`
   ></feature-feedback>`;
 ```
 
+### Feedback Survey widget for multi-question feedback
+
+```ts
+  import { RecaptchaManager } from '@internetarchive/recaptcha-manager';
+  import { SharedResizeObserver } from '@internetarchive/shared-resize-observer';
+  import { FeatureFeedbackService } from '@internetarchive/feature-feedback';
+  import '@internetarchive/feature-feedback';
+
+  const recaptchaManager = new RecaptchaManager({
+    defaultSiteKey: '',
+  });
+  const featureFeedbackService = new FeatureFeedbackService({
+    serviceUrl: 'http://local.archive.org:5000',
+  });
+  const resizeObserver = new SharedResizeObserver();
+
+  html`
+    <ia-feedback-survey
+      .recaptchaManager=${recaptchaManager}
+      .featureFeedbackService=${featureFeedbackService}
+      .resizeObserver=${resizeObserver}
+      .surveyIdentifier=${'demo-survey'}
+      .buttonText=${'Take the survey'}
+      showButtonThumbs
+      showQuestionNumbers
+    >
+      <ia-survey-vote
+        prompt="Do you find foos better than bars?"
+        showComments
+        required
+      ></ia-survey-vote>
+      <ia-survey-vote
+        prompt="Would you recommend foos to a friend?"
+      ></ia-survey-vote>
+      <ia-survey-comment
+        prompt="Anything else to add?"
+        placeholder="Add optional comments..."
+      ></ia-survey-comment>
+      <ia-survey-extra name="Search query" value=${this.query}>
+    </ia-feedback-survey>
+  `;
+```
+
+#### Feedback survey question components
+
+Currently this package defines three subcomponents that can be used as survey "questions":
+ - `<ia-survey-vote>`: Seeks an up/down vote, optionally with a freeform text comment too -- like the single-question feature feedback widget.
+Accepts the following attributes/properties:
+   - `prompt` (string): The question text to display beside the vote buttons. If not provided, no prompt text will be rendered.
+   - `vote` ("up" | "down"): Optionally allows setting the initial up/down vote state of the question if desired.
+   - `comment` (string): Optionally allows setting the comment response for the question if desired.
+   - `showComments` (boolean): If true, shows a freeform textarea beneath the vote buttons.
+   - `commentPlaceholder` (string): The placeholder text to render in the textarea when it is empty (see `placeholder` for `<ia-survey-comment>` below).
+   - `required` (boolean): If true, ensures that the survey cannot be submitted unless a vote is entered for this question.
+   A text comment is never required for these questions, even when shown. To require text input, use a separate `<ia-survey-comment>` question.
+   - `disabled` (boolean): If true, the question will not allow the vote to be changed or the comment to be edited by the user.
+   - `skipNumber` (boolean): If true, this question will not participate in question numbering -- it will neither display a number itself nor increment the
+   number used for the next question.
+
+ - `<ia-survey-comment>`: Seeks a freeform text comment alone. Accepts the following attributes/properties:
+   - `prompt` (string): The question text to display above the textarea. If not provided, no prompt text will be rendered.
+   - `value` (string): Optionally allows setting the comment response for the question if desired.
+   - `placeholder` (string): The placeholder text to render in the textarea when it is empty.
+   If not provided, a default of either `Comments` or `Comments (optional)` will be used, depending on the `required` state of this component.
+   - `required` (boolean): If true, ensures that the survey cannot be submitted unless a non-empty comment is entered for this question.
+   - `disabled` (boolean): If true, the question will not allow the user to edit the comment.
+   - `skipNumber` (boolean): If true, this question will not participate in question numbering -- it will neither display a number itself nor increment the
+   number used for the next question.
+
+ - `<ia-survey-extra>`: Does not render a question to the user, but instead defines additional info to be submitted with survey responses for context.
+ Accepts the following attributes/properties:
+   - `name` (string): A name to associate with this extra info field.
+   - `value` (string): The value of this field to be submitted in the survey response.
+
+One may define additional question components that can participate in survey responses, as long as they conform to the `IASurveyQuestionInterface`.
+
+Other arbitrary elements may also be included presentationally within the survey, to be slotted into the popup alongside any questions.
+Such elements will generally not have any effect on submitted survey responses unless they conform to the interface noted above.
+
+#### Styling
+
+Both the `<ia-survey-vote>` and `<ia-survey-comment>` components accept optional CSS variables to adjust the height or resizability of their comment textareas:
+ - `--commentHeight` (defaults to `50px`)
+ - `--commentResize` (`none`, `horizontal`, `vertical`, or `both` -- defaults to `none`). See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/resize) for more details.
+
 
 ## Local Demo with `web-dev-server`
 ```bash

demo/app-root.ts

@@ -2,13 +2,17 @@ import { RecaptchaManager } from '@internetarchive/recaptcha-manager';
 import { SharedResizeObserver } from '@internetarchive/shared-resize-observer';
 import { html, css, LitElement } from 'lit';
 import { customElement } from 'lit/decorators.js';
-import '../src/feature-feedback';
 import { FeatureFeedbackService } from '../src/feature-feedback-service';
+import '../src/feature-feedback';
+import '../src/survey/ia-feedback-survey';
+import '../src/survey/questions/ia-survey-vote';
+import '../src/survey/questions/ia-survey-comment';
+import '../src/survey/questions/ia-survey-extra';
 
 @customElement('app-root')
 export class AppRoot extends LitElement {
   recaptchaManager = new RecaptchaManager({
-    defaultSiteKey: '',
+    defaultSiteKey: 'foo',
   });
 
   featureFeedbackService = new FeatureFeedbackService({
@@ -96,6 +100,50 @@ export class AppRoot extends LitElement {
         fugiat. Aute excepteur enim ad consectetur duis eu aute sint fugiat.
         Nulla cillum fugiat tempor esse non eu dolore adipisicing magna.
       </p>
+
+      <ia-feedback-survey
+        showButtonThumbs
+        showQuestionNumbers
+        .surveyIdentifier=${'demo-survey'}
+        .recaptchaManager=${this.recaptchaManager}
+        .featureFeedbackService=${this.featureFeedbackService}
+        .resizeObserver=${this.resizeObserver}
+      >
+        <ia-survey-vote
+          prompt="How do you feel about foo?"
+          required
+        ></ia-survey-vote>
+        <ia-survey-extra name="foo" value="bar"></ia-survey-extra>
+        <p>
+          This is some embedded explanatory text. The above question requires a
+          response, but the next question is optional.
+        </p>
+        <ia-survey-vote
+          prompt="How do you feel about bar?"
+          showComments
+          commentPlaceholder="You may enter an optional comment as well..."
+        ></ia-survey-vote>
+        <p>The following question should be disabled.</p>
+        <ia-survey-vote
+          prompt="How do you feel about baz?"
+          disabled
+        ></ia-survey-vote>
+        <p>The following question should not be numbered.</p>
+        <ia-survey-vote
+          prompt="How do you feel about quux?"
+          skipNumber
+        ></ia-survey-vote>
+        <ia-survey-comment
+          prompt="What does foobar mean to you?"
+          placeholder="You must answer this question."
+          required
+        ></ia-survey-comment>
+        <ia-survey-comment
+          prompt="Anything else to add?"
+          placeholder="Please share... (optional)"
+          style="--commentResize: vertical;"
+        ></ia-survey-comment>
+      </ia-feedback-survey>
     `;
   }
 
@@ -107,5 +155,9 @@ export class AppRoot extends LitElement {
     .right {
       float: right;
     }
+
+    ia-feedback-survey > p {
+      font-size: 12px;
+    }
   `;
 }

demo/index.html

@@ -4,6 +4,10 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <style>
+    html, body {
+      height: 100%;
+    }
+
     html {
       font-size: 10px; /* This is to match petabox's base font size */
       font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;

index.ts

@@ -3,3 +3,12 @@ export {
   FeatureFeedbackService,
   FeatureFeedbackServiceInterface,
 } from './src/feature-feedback-service';
+
+export { IAFeedbackSurvey } from './src/survey/ia-feedback-survey';
+export { IASurveyComment } from './src/survey/questions/ia-survey-comment';
+export { IASurveyVote } from './src/survey/questions/ia-survey-vote';
+export { IASurveyExtra } from './src/survey/questions/ia-survey-extra';
+export {
+  IASurveyQuestionInterface,
+  IASurveyQuestionResponse,
+} from './src/survey/models';

package.json

@@ -22,26 +22,30 @@
   },
   "types": "dist/index.d.ts",
   "dependencies": {
+    "@internetarchive/ia-styles": "^1.0.0",
     "@internetarchive/recaptcha-manager": "^0.1.1",
     "@internetarchive/result-type": "^0.0.1",
     "@internetarchive/shared-resize-observer": "^0.2.0",
+    "@lit/localize": "^0.11.4",
     "lit": "^2.2.7"
   },
   "devDependencies": {
     "@open-wc/eslint-config": "^7.0.0",
-    "@open-wc/testing": "^3.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.3.1",
-    "@typescript-eslint/parser": "^5.3.1",
-    "@web/dev-server": "^0.1.28",
-    "@web/test-runner": "^0.13.22",
+    "@open-wc/testing": "^4.0.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.15.29",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@web/dev-server": "^0.4.6",
+    "@web/test-runner": "^0.20.0",
     "concurrently": "^6.3.0",
     "eslint": "^8.2.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-import": "^2.25.3",
     "eslint-plugin-lit-a11y": "^2.2.0",
     "eslint-plugin-wc": "^1.3.2",
     "husky": "^7.0.0",
-    "madge": "^5.0.1",
+    "madge": "^8.0.0",
     "prettier": "^2.4.1",
     "sinon": "^12.0.1",
     "tslib": "^2.3.1",
@@ -64,6 +68,10 @@
     },
     "rules": {
       "no-unused-vars": "off",
+      "no-param-reassign": [
+        "error",
+        { "props": false }
+      ],
       "@typescript-eslint/no-unused-vars": [
         "error"
       ],

src/feature-feedback-service.ts

@@ -1,13 +1,35 @@
 import type { Result } from '@internetarchive/result-type';
 import { Vote } from './models';
+import { IASurveyQuestionResponse } from './survey/models';
 
 export interface FeatureFeedbackServiceInterface {
+  /**
+   * Submits a feedback entry to the configured service URL.
+   * @param options Details about the survey:
+   *  - `featureIdentifier`: Internal identifier for the feature being rated
+   *  - `vote`: The up/down rating for the feature
+   *  - `comments`: (Optional) A text comment about the feature
+   *  - `recaptchaToken`: Token generated by the ReCAPTCHA service
+   */
   submitFeedback(options: {
     featureIdentifier: string;
     vote: Vote;
     comments?: string;
     recaptchaToken: string;
   }): Promise<Result<boolean, Error>>;
+
+  /**
+   * Submits a set of survey responses to the configured service URL.
+   * @param options Details about the survey:
+   *  - `surveyIdentifier`: Internal identifier of the survey to be submitted
+   *  - `responses`: List of responses to the survey questions
+   *  - `recaptchaToken`: Token generated by the ReCAPTCHA service
+   */
+  submitSurvey(options: {
+    surveyIdentifier: string;
+    responses: IASurveyQuestionResponse[];
+    recaptchaToken: string;
+  }): Promise<Result<boolean, Error>>;
 }
 
 export class FeatureFeedbackService implements FeatureFeedbackServiceInterface {
@@ -17,6 +39,9 @@ export class FeatureFeedbackService implements FeatureFeedbackServiceInterface {
     this.serviceUrl = options.serviceUrl;
   }
 
+  /**
+   * @inheritdoc
+   */
   async submitFeedback(options: {
     featureIdentifier: string;
     vote: Vote;
@@ -50,4 +75,48 @@ export class FeatureFeedbackService implements FeatureFeedbackServiceInterface {
       };
     }
   }
+
+  /**
+   * @inheritdoc
+   */
+  async submitSurvey(options: {
+    surveyIdentifier: string;
+    responses: IASurveyQuestionResponse[];
+    recaptchaToken: string;
+  }): Promise<Result<boolean, Error>> {
+    const url = new URL(this.serviceUrl);
+    url.searchParams.append('surveyId', options.surveyIdentifier);
+    url.searchParams.append('token', options.recaptchaToken);
+    const body = JSON.stringify({
+      surveyResponses: options.responses.map(resp => ({
+        name: resp.name,
+        ...(resp.rating ? { rating: resp.rating } : {}),
+        ...(resp.comment ? { comment: resp.comment } : {}),
+      })),
+    });
+
+    try {
+      const response = await fetch(url.href, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      });
+      const json = await response.json();
+      return json as Result<boolean, Error>;
+    } catch (error) {
+      let err: Error;
+      if (error instanceof Error) {
+        err = error;
+      } else if (typeof error === 'string') {
+        err = new Error(error);
+      } else {
+        err = new Error('Unknown error');
+      }
+
+      return {
+        success: false,
+        error: err,
+      };
+    }
+  }
 }