@genspectrum/dashboard-components 1.17.0 → 1.18.1

package/src/preact/mutationsOverTime/getFilteredMutationCodes.ts

@@ -94,10 +94,10 @@ function mutationOrAnnotationMatchesTextFilter(
         return false;
     }
     return mutationAnnotations.some(
-        (annotation) =>
-            annotation.description.includes(textFilter) ||
-            annotation.name.includes(textFilter) ||
-            annotation.symbol.includes(textFilter),
+        (resolved) =>
+            resolved.annotation.description.includes(textFilter) ||
+            resolved.annotation.name.includes(textFilter) ||
+            resolved.annotation.symbol.includes(textFilter),
     );
 }
 
@@ -115,5 +115,5 @@ function mutationMatchesAnnotationFilter(
     if (mutationAnnotations === undefined || mutationAnnotations.length === 0) {
         return false;
     }
-    return mutationAnnotations.some((annotation) => annotationNameFilter.has(annotation.name));
+    return mutationAnnotations.some((resolved) => annotationNameFilter.has(resolved.annotation.name));
 }

package/src/web-components/gs-app.ts

@@ -45,6 +45,10 @@ export class AppComponent extends LitElement {
     /**
      * Supply lists of mutations that are especially relevant for the current organism.
      *
+     * Each entry in `nucleotideMutations`, `aminoAcidMutations`, `nucleotidePositions`, and `aminoAcidPositions`
+     * can be either a plain string or an object with an optional `name` and `description` that override the
+     * group-level values in the annotation popup for that specific mutation or position.
+     *
      * Visit https://genspectrum.github.io/dashboard-components/?path=/docs/concepts-mutation-annotations--docs for more information.
      */
     @provide({ context: mutationAnnotationsContext })
@@ -53,10 +57,10 @@ export class AppComponent extends LitElement {
         name: string;
         description: string;
         symbol: string;
-        nucleotideMutations?: string[];
-        nucleotidePositions?: string[];
-        aminoAcidMutations?: string[];
-        aminoAcidPositions?: string[];
+        nucleotideMutations?: (string | { mutation: string; name?: string; description?: string })[];
+        nucleotidePositions?: (string | { position: string; name?: string; description?: string })[];
+        aminoAcidMutations?: (string | { mutation: string; name?: string; description?: string })[];
+        aminoAcidPositions?: (string | { position: string; name?: string; description?: string })[];
     }[] = [];
 
     /**

package/src/web-components/mutation-annotations-context.ts

@@ -1,16 +1,24 @@
 import { createContext } from '@lit/context';
 import z from 'zod';
 
-const annotations = z.array(z.string());
+const mutationEntrySchema = z.union([
+    z.string(),
+    z.object({ mutation: z.string(), name: z.string().optional(), description: z.string().optional() }),
+]);
+
+const positionEntrySchema = z.union([
+    z.string(),
+    z.object({ position: z.string(), name: z.string().optional(), description: z.string().optional() }),
+]);
 
 const mutationAnnotationSchema = z.object({
     name: z.string(),
     description: z.string(),
     symbol: z.string(),
-    nucleotideMutations: annotations.optional(),
-    nucleotidePositions: annotations.optional(),
-    aminoAcidMutations: annotations.optional(),
-    aminoAcidPositions: annotations.optional(),
+    nucleotideMutations: z.array(mutationEntrySchema).optional(),
+    nucleotidePositions: z.array(positionEntrySchema).optional(),
+    aminoAcidMutations: z.array(mutationEntrySchema).optional(),
+    aminoAcidPositions: z.array(positionEntrySchema).optional(),
 });
 export type MutationAnnotation = z.infer<typeof mutationAnnotationSchema>;
 

package/src/web-components/mutationAnnotations.mdx

@@ -39,3 +39,32 @@ The annotation can be applied to specific mutations:
 - `nucleotideMutations: [C44T]` matches only the nucleotide mutation `C44T`,
 - `aminoAcidPositions: [S:123]` matches all amino acid mutations that occur on the gene `S` at position `123`
 - If the pathogen has only one segment, one can omit the segment, writing `123` for any mutation at position `123`.
+
+## Per-mutation name and description
+
+Instead of a plain string, each entry in `nucleotideMutations`, `aminoAcidMutations`, `nucleotidePositions`, and `aminoAcidPositions` can be an object with optional `name` and `description` fields.
+These override the group-level `name` and `description` in the popup for that specific mutation, while the group-level values remain as fallback for entries that don't specify their own.
+
+This is useful when grouping mutations under a shared symbol (e.g. all mutations of one drug target) while still showing per-mutation details in the popup:
+
+```html
+<gs-app
+    lapis="https://your.lapis.url"
+    mutationAnnotations="[
+        {
+            name: '3CLpro inhibitor resistance',
+            description: 'Mutations affecting 3CLpro drug binding.',
+            symbol: 'c',
+            nucleotideMutations: [
+                { mutation: 'ORF1a:T2343C', name: '3CLpro:T31C', description: 'Disrupts nirmatrelvir binding.' },
+                { mutation: 'ORF1a:G2558A', name: '3CLpro:E166K' },
+                'ORF1a:C2566T'
+            ]
+        },
+    ]"
+>
+    {/* children... */}
+</gs-app>
+```
+
+In this example, clicking `ORF1a:T2343C` shows `3CLpro:T31C` as the title and the specific description, clicking `ORF1a:G2558A` shows `3CLpro:E166K` but falls back to the group description, and clicking `ORF1a:C2566T` falls back to both the group name and description.