@spotify/backstage-plugin-pulse-common 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -98,11 +98,7 @@ interface Question {
     /**
      * The question description, in markdown
      */
-    text?: string;
-    /**
-     * The question description, in HTML
-     */
-    text_html?: string;
+    text: string;
     /**
      * The type of question
      */
@@ -146,7 +142,7 @@ interface Question {
         /**
          * The id of the group.
          */
-        id?: string;
+        id: string;
         /**
          * The display name of the group
          */
@@ -167,7 +163,7 @@ interface Question {
         /**
          * The id of the group.
          */
-        id?: string;
+        id: string;
         /**
          * The display name of the group
          */
@@ -233,7 +229,7 @@ interface Choice {
     /**
      * If a textbox should appear next to the choice, and if it should be mandatory to fill it in if the choice is selected
      */
-    text?: 'no' | 'optional' | 'forced';
+    text_input?: 'no' | 'optional' | 'forced';
     /**
      * If true, this choice can't be combined with other choices in this question
      */
@@ -260,6 +256,61 @@ declare const validateTemplate: (template: SurveyTemplate) => void;
  * @public */
 declare const interpolateTemplate: (template: SurveyTemplate) => SurveyTemplate;
 
+/** @public */
+declare enum LOCATOR_EXPRESSION {
+    ALL = "all",
+    ALL_ENTERED_TEXT = "all_entered_text",
+    SELECTED = "selected",
+    SELECTED_ENTERED_TEXT = "selected_entered_text",
+    NOT_SELECTED = "not_selected",
+    FOR_MATRIX_CHOICE = "for_matrix_choice",
+    UNSELECTED_FOR_MATRIX_CHOICE = "unselected_for_matrix_choice",
+    DISPLAYED = "displayed",
+    NOT_DISPLAYED = "not_displayed"
+}
+/** @public */
+type Locator = {
+    questionId: string;
+    expression: LOCATOR_EXPRESSION;
+    identifier?: string | number;
+};
+/** @public */
+declare const validateLocator: (locatorExpression: string) => boolean;
+/** @public */
+declare const parseLocator: (locatorExpression: string) => Locator;
+
+/** @public */
+type Answer = {
+    choiceId?: string | null;
+    choiceValue?: number | null;
+    text?: string | null;
+};
+/** @public */
+type SurveyQuestionResponse = {
+    id: string;
+    surveyId: string;
+    questionId: string;
+    surveyResponseId: string;
+    /** The ID of the statement. Only set if question.type is MATRIX_SINGLE or MATRIX_MULTI. */
+    statementId?: string | null;
+    /** The selected choices for multiple answer questions (mc-multi, matrix-multi). */
+    multipleAnswers?: readonly Answer[] | null;
+    /** The selected choice for single answer questions (mc-single, matrix-single). */
+    singleAnswer?: Answer | null;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/** @public */
+type StatementWithGroupInfo = Statement & {
+    groupId?: string;
+    groupDisplay?: string;
+};
+/** @public */
+type ChoiceWithGroupInfo = Choice & {
+    groupId?: string;
+    groupDisplay?: string;
+};
+
 /** Refers to a specific choice in a specific question/statement
  * If statementId is defined, questionId.statementId is the full path
  * to this choice
@@ -276,16 +327,71 @@ type MatrixStatementRef = {
     statementId: string;
 };
 /** @public */
-type LogicContextEvaluator = {
+declare const getAnswerValue: (answer: Answer) => string | number;
+/** @public */
+type TemplateContextEvaluatorOptions = {
+    surveyId?: string;
+    templateId?: string;
     surveyResponseId?: string;
-    isSelected: (choice: ChoiceRef) => boolean;
-    isDisplayed: (choice: ChoiceRef) => boolean;
-    countSelected: (questionId: string) => number;
-    countChoiceSelections: (questionId: string, choice: number | string) => number;
-    textEntry: (choiceRef: ChoiceRef) => string;
+    questions: Question[];
+    questionResponses: SurveyQuestionResponse[];
 };
-/** @public */
-declare function evaluateExpression(expression: string, contextEvaluator: LogicContextEvaluator): any;
+/**
+ * Provides useful methods for making template schema evaluations given a particular response context
+ * @public */
+declare class TemplateContextEvaluator {
+    #private;
+    surveyId?: string;
+    templateId?: string;
+    surveyResponseId?: string;
+    questions: Question[];
+    questionResponses: SurveyQuestionResponse[];
+    constructor(options: TemplateContextEvaluatorOptions);
+    /**
+     * Returns the relevant answers for a particular question. If a statement ID or choice
+     * identifier is provided, answers will be filtered to those matching the specified
+     * inputs.
+     */
+    getQuestionAnswers(questionId: string, statementId?: string | null, choiceIdOrValue?: string | number | null): Answer[];
+    /**
+     * Returns the list of choices or statements referenced by a locator taking into
+     * account the current response context.
+     */
+    evaluateDynamicExpression<T extends Choice | Statement>(locator: Locator, target: 'choices' | 'statements'): T[];
+    isStatementSelected(statement: MatrixStatementRef): boolean;
+    isSelected(choice: ChoiceRef): boolean;
+    isDisplayed(_: ChoiceRef): boolean;
+    countSelected(questionId: string): number;
+    countChoiceSelections(questionId: string, choice: number | string): number;
+    textEntry(choice: ChoiceRef): string;
+}
+/**
+ * Returns a context evaluator with no responses which effectively means most
+ * display logic expressions would evaluate to false. This evaluator is useful when
+ * there is no existing surver response such as when a user first begins taking a survey.
+ * @public */
+declare const getBaseContextEvaluator: (questions?: Question[]) => TemplateContextEvaluator;
+/**
+ * Evaluates a display logic expression using the given response context
+ * @public */
+declare const evaluateDisplayLogic: (evaluator: TemplateContextEvaluator, expression?: string) => boolean;
+/**
+ * Returns the question text with any dynamic expressions interpolated.
+ * @public
+ */
+declare const getQuestionText: (question: Question, evaluator?: TemplateContextEvaluator | null) => string;
+/**
+ * Returns all choices that are valid for a particular question given a specific
+ * response context. This takes into account choices that are in groups and
+ * dynamic choices that may come from other questions.
+ *  @public */
+declare const getQuestionChoices: (question: Question, evaluator?: TemplateContextEvaluator | null) => ChoiceWithGroupInfo[];
+/**
+ * Returns all statements that are valid for a particular question given a specific
+ * response context. This takes into account statements that are in groups and
+ * dynamic statements that may come from other questions.
+ * @public */
+declare const getQuestionStatements: (question: Question, evaluator?: TemplateContextEvaluator | null) => StatementWithGroupInfo[];
 
 /** @public */
 declare const templateSchema: {
@@ -297,7 +403,6 @@ declare const templateSchema: {
         template: {
             type: string;
             description: string;
-            /** @public */
             properties: {
                 id: {
                     type: string;
@@ -446,10 +551,6 @@ declare const templateSchema: {
                     type: string;
                     description: string;
                 };
-                text_html: {
-                    type: string;
-                    description: string;
-                };
                 type: {
                     type: string;
                     enum: string[];
@@ -577,15 +678,10 @@ declare const templateSchema: {
                 };
             };
             additionalProperties: boolean;
-            allOf: ({
-                oneOf: {
-                    required: string[];
-                }[];
-            } | {
-                oneOf: {
-                    $ref: string;
-                }[];
-            })[];
+            required: string[];
+            oneOf: {
+                $ref: string;
+            }[];
         };
         "question-mc-horizontal": {
             type: string;
@@ -740,7 +836,7 @@ declare const templateSchema: {
                     type: string;
                     description: string;
                 };
-                text: {
+                text_input: {
                     type: string;
                     enum: string[];
                     description: string;
@@ -819,4 +915,4 @@ declare const permissions: {
     surveyAdministerPermission: _backstage_plugin_permission_common.BasicPermission;
 };
 
-export { Choice, ChoiceRef, DEFAULT_TEMPLATE_ID, LogicContextEvaluator, MatrixStatementRef, Page, Question, Randomization, Section, Statement, SurveyTemplate, evaluateExpression, interpolateTemplate, permissions, templateSchema, validateTemplate };
+export { Answer, Choice, ChoiceRef, ChoiceWithGroupInfo, DEFAULT_TEMPLATE_ID, LOCATOR_EXPRESSION, Locator, MatrixStatementRef, Page, Question, Randomization, Section, Statement, StatementWithGroupInfo, SurveyQuestionResponse, SurveyTemplate, TemplateContextEvaluator, TemplateContextEvaluatorOptions, evaluateDisplayLogic, getAnswerValue, getBaseContextEvaluator, getQuestionChoices, getQuestionStatements, getQuestionText, interpolateTemplate, parseLocator, permissions, templateSchema, validateLocator, validateTemplate };