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

package/dist/index.d.ts

@@ -54,7 +54,7 @@ interface SurveyTemplate {
         default?: string | number | boolean;
     }[];
     /**
-     * Expression shortcuts. Macros are referred to elsewhere in the survey using the $\{p:<name>\} construct (same as parameters) and will get lazily in-place replaced. Macros can be recursive and contain references to parameters or answers in the survey.
+     * Expression shortcuts. Macros are referred to elsewhere in the survey using the $\{m:<name>\} construct (similar to parameters) and will get lazily in-place replaced. Macros can be recursive and contain references to parameters or answers in the survey.
      */
     macros?: {
         [k: string]: string;
@@ -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
      */
@@ -144,9 +140,9 @@ interface Question {
     statement_groups?: {
         statements: Statement[];
         /**
-         * The id of the group. Need only be set if referenced to in constrained randomization.
+         * The id of the group.
          */
-        id?: string;
+        id: string;
         /**
          * The display name of the group
          */
@@ -165,9 +161,9 @@ interface Question {
     choice_groups?: {
         choices: Choice[];
         /**
-         * The id of the group. Need only be set if referenced to in constrained randomization.
+         * 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
      */
@@ -250,6 +246,153 @@ interface Page {
 /** @public */
 declare const validateTemplate: (template: SurveyTemplate) => void;
 
+/**
+ * Mutates the template by replacing all references to $\{m:<macro>\} with
+ * the evaluation of the macro. This can and must be done once after
+ * loading the template and before evaluating any expression etc.
+ *
+ * The interpolation is idempotent.
+ *
+ * @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
+ * @public */
+type ChoiceRef = {
+    questionId: string;
+    statementId?: string;
+    choice: string | number;
+};
+/** Refers to a specific statement in a matrix
+ * @public */
+type MatrixStatementRef = {
+    questionId: string;
+    statementId: string;
+};
+/** @public */
+declare const getAnswerValue: (answer: Answer) => string | number;
+/** @public */
+type TemplateContextEvaluatorOptions = {
+    surveyId?: string;
+    templateId?: string;
+    surveyResponseId?: string;
+    questions: Question[];
+    questionResponses: SurveyQuestionResponse[];
+};
+/**
+ * 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: {
     $id: string;
@@ -408,10 +551,6 @@ declare const templateSchema: {
                     type: string;
                     description: string;
                 };
-                text_html: {
-                    type: string;
-                    description: string;
-                };
                 type: {
                     type: string;
                     enum: string[];
@@ -539,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;
@@ -702,7 +836,7 @@ declare const templateSchema: {
                     type: string;
                     description: string;
                 };
-                text: {
+                text_input: {
                     type: string;
                     enum: string[];
                     description: string;
@@ -781,4 +915,4 @@ declare const permissions: {
     surveyAdministerPermission: _backstage_plugin_permission_common.BasicPermission;
 };
 
-export { Choice, DEFAULT_TEMPLATE_ID, Page, Question, Randomization, Section, Statement, SurveyTemplate, 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 };