@genspectrum/dashboard-components 1.17.0 → 1.18.0

package/src/preact/MutationAnnotationsContext.tsx

@@ -11,12 +11,18 @@ import { ErrorDisplay } from './components/error-display';
 import { ResizeContainer } from './components/resize-container';
 import { type Mutation } from '../utils/mutations';
 
-type MutationAnnotationPerSequenceType = {
-    mutation: Map<string, MutationAnnotations>;
-    position: Map<string, MutationAnnotations>;
+export type ResolvedMutationAnnotation = {
+    annotation: MutationAnnotation;
+    name: string;
+    description: string;
 };
 
-type MutationAnnotationsContextValue = Record<SequenceType, MutationAnnotationPerSequenceType> & {
+type AnnotationLookup = {
+    mutation: Map<string, ResolvedMutationAnnotation[]>;
+    position: Map<string, ResolvedMutationAnnotation[]>;
+};
+
+type MutationAnnotationsContextValue = Record<SequenceType, AnnotationLookup> & {
     rawAnnotations: MutationAnnotations;
 };
 
@@ -32,69 +38,113 @@ const MutationAnnotationsContext = createContext<MutationAnnotationsContextValue
     },
 });
 
+/**
+ * Validates and provides mutation annotations to all descendant components.
+ * Accepts the raw MutationAnnotations config, builds the internal lookup index, and stores it in context.
+ * Renders an error message if the provided annotations fail schema validation.
+ */
 export const MutationAnnotationsContextProvider: FunctionalComponent<
     Omit<ComponentProps<typeof MutationAnnotationsContext.Provider>, 'value'> & { value: MutationAnnotations }
 > = ({ value, children }) => {
-    const parseResult = useMemo(() => {
-        const parseResult = mutationAnnotationsSchema.safeParse(value);
-
-        if (!parseResult.success) {
-            return parseResult;
-        }
-
-        return { success: true as const, value: getMutationAnnotationsContext(value) };
-    }, [value]);
+    const parseResult = useMemo(() => mutationAnnotationsSchema.safeParse(value), [value]);
+    const contextValue = useMemo(
+        () =>
+            parseResult.success
+                ? { success: true as const, value: buildAnnotationIndex(parseResult.data) }
+                : { success: false as const, error: parseResult.error },
+        [parseResult],
+    );
 
-    if (!parseResult.success) {
+    if (!contextValue.success) {
         return (
             <ResizeContainer size={{ width: '100%' }}>
-                <ErrorDisplay error={parseResult.error} layout='vertical' />
+                <ErrorDisplay error={contextValue.error} layout='vertical' />
             </ResizeContainer>
         );
     }
 
     return (
-        <MutationAnnotationsContext.Provider value={parseResult.value}>{children}</MutationAnnotationsContext.Provider>
+        <MutationAnnotationsContext.Provider value={contextValue.value}>{children}</MutationAnnotationsContext.Provider>
     );
 };
 
-export function getMutationAnnotationsContext(value: MutationAnnotations) {
-    const nucleotideMap = new Map<string, MutationAnnotations>();
-    const nucleotidePositions = new Map<string, MutationAnnotations>();
-    const aminoAcidMap = new Map<string, MutationAnnotations>();
-    const aminoAcidPositions = new Map<string, MutationAnnotations>();
+/**
+ * Indexes a flat list of MutationAnnotations into fast lookup maps, resolving per-entry name/description overrides
+ * eagerly. Called once (memoized) when the annotations config is set on the provider.
+ *
+ * Returns two maps per sequence type — one keyed by exact mutation code, one by position string — each mapping to
+ * the list of ResolvedMutationAnnotations that apply to that key.
+ */
+export function buildAnnotationIndex(value: MutationAnnotations): MutationAnnotationsContextValue {
+    const nucleotideMutationMap = new Map<string, ResolvedMutationAnnotation[]>();
+    const nucleotidePositionMap = new Map<string, ResolvedMutationAnnotation[]>();
+    const aminoAcidMutationMap = new Map<string, ResolvedMutationAnnotation[]>();
+    const aminoAcidPositionMap = new Map<string, ResolvedMutationAnnotation[]>();
 
     value.forEach((annotation) => {
-        new Set(annotation.nucleotideMutations).forEach((code) => {
-            addAnnotationToMap(nucleotideMap, code, annotation);
+        annotation.nucleotideMutations?.forEach((entry) => {
+            addToMap(
+                nucleotideMutationMap,
+                typeof entry === 'string' ? entry : entry.mutation,
+                resolve(annotation, entry),
+            );
         });
-        new Set(annotation.aminoAcidMutations).forEach((code) => {
-            addAnnotationToMap(aminoAcidMap, code, annotation);
+        annotation.aminoAcidMutations?.forEach((entry) => {
+            addToMap(
+                aminoAcidMutationMap,
+                typeof entry === 'string' ? entry : entry.mutation,
+                resolve(annotation, entry),
+            );
         });
-        new Set(annotation.nucleotidePositions).forEach((position) => {
-            addAnnotationToMap(nucleotidePositions, position, annotation);
+        annotation.nucleotidePositions?.forEach((entry) => {
+            addToMap(
+                nucleotidePositionMap,
+                typeof entry === 'string' ? entry : entry.position,
+                resolve(annotation, entry),
+            );
         });
-        new Set(annotation.aminoAcidPositions).forEach((position) => {
-            addAnnotationToMap(aminoAcidPositions, position, annotation);
+        annotation.aminoAcidPositions?.forEach((entry) => {
+            addToMap(
+                aminoAcidPositionMap,
+                typeof entry === 'string' ? entry : entry.position,
+                resolve(annotation, entry),
+            );
         });
     });
 
     return {
         rawAnnotations: value,
-        nucleotide: { mutation: nucleotideMap, position: nucleotidePositions },
-        'amino acid': { mutation: aminoAcidMap, position: aminoAcidPositions },
+        nucleotide: { mutation: nucleotideMutationMap, position: nucleotidePositionMap },
+        'amino acid': { mutation: aminoAcidMutationMap, position: aminoAcidPositionMap },
+    };
+}
+
+function resolve(
+    annotation: MutationAnnotation,
+    entry: string | { name?: string; description?: string },
+): ResolvedMutationAnnotation {
+    const overrides = typeof entry === 'object' ? entry : undefined;
+    return {
+        annotation,
+        name: overrides?.name ?? annotation.name,
+        description: overrides?.description ?? annotation.description,
     };
 }
 
-function addAnnotationToMap(map: Map<string, MutationAnnotations>, code: string, annotation: MutationAnnotation) {
-    const oldAnnotations = map.get(code.toUpperCase()) ?? [];
-    map.set(code.toUpperCase(), [...oldAnnotations, annotation]);
+function addToMap(map: Map<string, ResolvedMutationAnnotation[]>, code: string, resolved: ResolvedMutationAnnotation) {
+    const existing = map.get(code.toUpperCase()) ?? [];
+    map.set(code.toUpperCase(), [...existing, resolved]);
 }
 
 export function useRawMutationAnnotations() {
     return useContext(MutationAnnotationsContext).rawAnnotations;
 }
 
+/**
+ * Returns a lookup function `(mutation, sequenceType) => ResolvedMutationAnnotation[] | undefined` that, given a
+ * specific mutation, returns all annotations that apply to it with name and description already resolved.
+ * Returns undefined if no annotations match.
+ */
 export function useMutationAnnotationsProvider() {
     const mutationAnnotations = useContext(MutationAnnotationsContext);
 
@@ -108,21 +158,19 @@ export function getMutationAnnotationsProvider(mutationAnnotations: MutationAnno
                 ? `${mutation.position}`
                 : `${mutation.segment.toUpperCase()}:${mutation.position}`;
 
-        const possiblePositionAnnotations = mutationAnnotations[sequenceType].position.get(position);
-        const possibleExactAnnotations = mutationAnnotations[sequenceType].mutation.get(mutation.code.toUpperCase());
+        const exactMatches = mutationAnnotations[sequenceType].mutation.get(mutation.code.toUpperCase());
+        const positionMatches = mutationAnnotations[sequenceType].position.get(position);
 
-        const annotations =
-            possiblePositionAnnotations && possibleExactAnnotations
-                ? [...possiblePositionAnnotations, ...possibleExactAnnotations]
-                : (possiblePositionAnnotations ?? possibleExactAnnotations);
+        const combined =
+            exactMatches && positionMatches ? [...exactMatches, ...positionMatches] : (exactMatches ?? positionMatches);
 
-        const uniqueNames = new Set<string>();
+        const seenNames = new Set<string>();
 
-        return annotations?.filter((annotation) => {
-            if (uniqueNames.has(annotation.name)) {
+        return combined?.filter((resolved) => {
+            if (seenNames.has(resolved.annotation.name)) {
                 return false;
             }
-            uniqueNames.add(annotation.name);
+            seenNames.add(resolved.annotation.name);
             return true;
         });
     };

package/src/preact/components/annotated-mutation.stories.tsx

@@ -128,6 +128,37 @@ export const MutationWithMultipleAnnotationEntries: StoryObj<StoryProps> = {
     },
 };
 
+export const MutationWithPerMutationInfoOverride: StoryObj<StoryProps> = {
+    ...MutationWithoutAnnotationEntry,
+    args: {
+        ...MutationWithoutAnnotationEntry.args,
+        annotations: [
+            {
+                name: 'Group annotation',
+                description: 'Group-level description',
+                symbol: 'c',
+                nucleotideMutations: [
+                    {
+                        mutation: 'A23403G',
+                        name: '3CLpro:T31C',
+                        description: 'Per-mutation description for 3CLpro:T31C',
+                    },
+                ],
+            },
+        ],
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        await waitFor(() => expect(canvas.getByText('A23403G')).toBeVisible());
+        await expect(getAnnotationIndicator(canvas)).toBeVisible();
+
+        await userEvent.click(canvas.getByText('c'));
+        await waitFor(() => expect(canvas.queryByText('3CLpro:T31C')).toBeVisible());
+        await expect(canvas.queryByText('Per-mutation description for 3CLpro:T31C')).toBeVisible();
+    },
+};
+
 export const AminoAcidMutationWithAnnotationEntry: StoryObj<StoryProps> = {
     ...MutationWithoutAnnotationEntry,
     args: {

package/src/preact/components/annotated-mutation.tsx

@@ -78,11 +78,11 @@ const AnnotatedMutationWithoutContext: FunctionComponent<AnnotatedMutationWithou
     const modalContent = (
         <div className='block'>
             <InfoHeadline1>Annotations for {mutation.code}</InfoHeadline1>
-            {mutationAnnotations.map((annotation) => (
-                <Fragment key={annotation.name}>
-                    <InfoHeadline2>{annotation.name}</InfoHeadline2>
+            {mutationAnnotations.map((resolved) => (
+                <Fragment key={resolved.annotation.name}>
+                    <InfoHeadline2>{resolved.name}</InfoHeadline2>
                     <InfoParagraph>
-                        <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(annotation.description) }} />
+                        <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(resolved.description) }} />
                     </InfoParagraph>
                 </Fragment>
             ))}
@@ -99,7 +99,7 @@ const AnnotatedMutationWithoutContext: FunctionComponent<AnnotatedMutationWithou
             >
                 <sup className='hover:underline focus-visible:underline decoration-red-600'>
                     {mutationAnnotations
-                        .map((annotation) => annotation.symbol)
+                        .map((resolved) => resolved.annotation.symbol)
                         .map((symbol, index) => (
                             <Fragment key={symbol}>
                                 <span className='text-red-600'>{symbol}</span>

package/src/preact/mutationsOverTime/getFilteredMutationCodes.spec.ts

@@ -4,7 +4,7 @@ import { getFilteredMutationCodes, type MutationFilter } from './getFilteredMuta
 import { type DeletionEntry, type SubstitutionEntry } from '../../types';
 import { type Deletion, type Substitution } from '../../utils/mutations';
 import { type MutationAnnotations } from '../../web-components/mutation-annotations-context';
-import { getMutationAnnotationsContext, getMutationAnnotationsProvider } from '../MutationAnnotationsContext';
+import { buildAnnotationIndex, getMutationAnnotationsProvider } from '../MutationAnnotationsContext';
 
 describe('getFilteredMutationCodes', () => {
     it('should filter by displayed segments', () => {
@@ -129,7 +129,7 @@ describe('getFilteredMutationCodes', () => {
 
     describe('should filter by annotation', () => {
         const expectFilteredValue = (filterValue: MutationFilter, annotations: MutationAnnotations) => {
-            const annotationProvider = getMutationAnnotationsProvider(getMutationAnnotationsContext(annotations));
+            const annotationProvider = getMutationAnnotationsProvider(buildAnnotationIndex(annotations));
 
             const result = getFilteredMutationCodes({
                 overallMutationData: [someSubstitutionEntry, anotherSubstitutionEntry, someDeletionEntry],

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.