fix(surveys): Improve taxonomy for surveys (#18212)

frontend/src/lib/taxonomy.tsx

@@ -192,17 +192,21 @@ export const KEY_MAPPING: KeyMappingInterface = {
         },
         $survey_response: {
             label: 'Survey Response',
-            description: 'What the user responded with to the survey',
+            description: 'The response value for the first question in the survey.',
             examples: ['I love it!', 5, "['choice 1', 'choice 3']"],
         },
         $survey_name: {
             label: 'Survey Name',
-            description: 'The name of the survey',
+            description: 'The name of the survey.',
             examples: ['Product Feedback for New Product', 'Home page NPS'],
         },
+        $survey_questions: {
+            label: 'Survey Questions',
+            description: 'The questions asked in the survey.',
+        },
         $survey_id: {
             label: 'Survey ID',
-            description: 'The unique identifier for the survey',
+            description: 'The unique identifier for the survey.',
         },
         $device: {
             label: 'Device',
@@ -793,6 +797,35 @@ export function getKeyMapping(
             data.description = `${data.description} Data from the first time this user was seen.`
         }
         return data
+    } else if (value.startsWith('$survey_response/')) {
+        const surveyId = value.replace(/^\$survey_response\//, '')
+        if (surveyId) {
+            return {
+                label: `Survey Responded: ${surveyId}`,
+                description: `Whether the user responded to survey with ID: "${surveyId}".`,
+            }
+        }
+    } else if (value.startsWith('$survey_dismiss/')) {
+        const surveyId = value.replace(/^\$survey_dismiss\//, '')
+        if (surveyId) {
+            return {
+                label: `Survey Dismissed: ${surveyId}`,
+                description: `Whether the user dismissed survey with ID: "${surveyId}".`,
+            }
+        }
+    } else if (value.startsWith('$survey_response_')) {
+        const surveyIndex = value.replace(/^\$survey_response_/, '')
+        if (surveyIndex) {
+            const index = Number(surveyIndex) + 1
+            // yes this will return 21th, but I'm applying the domain logic of
+            // it being very unlikely that someone will have more than 20 questions,
+            // rather than hyper optimising the suffix.
+            const suffix = index === 1 ? 'st' : index === 2 ? 'nd' : index === 3 ? 'rd' : 'th'
+            return {
+                label: `Survey Response Question ID: ${surveyIndex}`,
+                description: `The response value for the ${index}${suffix} question in the survey.`,
+            }
+        }
     } else if (value.startsWith('$feature/')) {
         const featureFlagKey = value.replace(/^\$feature\//, '')
         if (featureFlagKey) {