@genspectrum/dashboard-components 0.1.2 → 0.1.4

package/dist/genspectrum-components.d.ts

@@ -7,18 +7,76 @@ import { PropertyValues } from '@lit/reactive-element';
 import { ReactiveElement } from '@lit/reactive-element';
 import { TemplateResult } from 'lit-html';
 
+/**
+ * ## Context
+ *
+ * This component displays aggregated data, which can provide an overview of the underlying data.
+ *
+ * It expects a list of fields to aggregate by and a filter to apply to the data.
+ */
+export declare class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * The fields to aggregate by.
+     */
+    fields: string[];
+    /**
+     * The views are used to display the aggregated data.
+     * In the table view, the data is presented in a table format where each field is a column,
+     * along with the aggregated value and its proportion.
+     * The proportion represents the ratio of the aggregated value to the total count of the data
+     * (considering the applied filter).
+     */
+    views: View_4[];
+    /**
+     * The filter to apply to the data.
+     */
+    filter: LapisFilter;
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
+    render(): JSX_2.Element;
+}
+
+/**
+ * ## Context
+ *
+ * This component provides the main application context.
+ * All other `gs-*` components must be (possibly nested) children of this component.
+ * It makes use of the [Lit Context](https://lit.dev/docs/data/context/) to
+ * - provide the URL to the LAPIS instance to all its children
+ * - fetch the reference genomes from LAPIS and provide it to all its children
+ *
+ * This will show an error message if the reference genome cannot be fetched
+ * (e.g., due to an invalid LAPIS URL).
+ *
+ * ## Shadow DOM
+ *
+ * This component does __not__ use a shadow DOM. Children of this component will be rendered directly in the light DOM.
+ */
 export declare class App extends LitElement {
+    /**
+     * The URL of the LAPIS instance that all children of this component will use.
+     */
     lapis: string;
-    referenceGenome: ReferenceGenome;
-    private updateReferenceGenome;
+    /* Excluded from this release type: referenceGenome */
+    /* Excluded from this release type: updateReferenceGenome */
     render(): TemplateResult<1> | undefined;
     createRenderRoot(): this;
 }
 
 declare type ConfidenceIntervalMethod = 'wilson' | 'none';
 
-declare type CustomSelectOption = {
-    label: string;
+declare type CustomSelectOption<CustomLabel extends string> = {
+    label: CustomLabel;
     dateFrom: string;
     dateTo: string;
 };
@@ -26,19 +84,38 @@ declare type CustomSelectOption = {
 /**
  * @fires {CustomEvent<{ dateFrom: string; dateTo: string; }>} gs-date-range-changed - When the date range has changed
  */
-export declare class DateRangeSelectorComponent extends PreactLitAdapter {
-    customSelectOptions: CustomSelectOption[];
+export declare class DateRangeSelectorComponent<CustomLabel extends string> extends PreactLitAdapter {
+    customSelectOptions: CustomSelectOption<CustomLabel>[];
     earliestDate: string | undefined;
+    initialValue: PresetOptionValues | CustomLabel | string | undefined;
     render(): JSX_2.Element;
 }
 
+declare class Deletion implements Mutation {
+    readonly segment: string | undefined;
+    readonly valueAtReference: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    constructor(segment: string | undefined, valueAtReference: string | undefined, position: number);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Deletion | null;
+}
+
+declare class Insertion implements Mutation {
+    readonly segment: string | undefined;
+    readonly position: number;
+    readonly insertedSymbols: string;
+    readonly code: string;
+    constructor(segment: string | undefined, position: number, insertedSymbols: string);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Insertion | null;
+}
+
 declare type LapisFilter = Record<string, string | number | null | boolean>;
 
 /**
- * ## Tag
- *
- * `gs-location-filter`
- *
  * ## Context
  *
  * This component provides an input field to specify filters for locations.
@@ -70,7 +147,7 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
      * The initial value to use for this location filter.
      * Must be of the form `valueForField1 / valueForField2 / ... / valueForFieldN`.
      */
-    value: string;
+    initialValue: string;
     /**
      * The fields to display in the location filter, in hierarchical order.
      * The top-level field should be the first entry in the array.
@@ -81,16 +158,72 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
     render(): JSX_2.Element;
 }
 
-export declare class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
-    variants: MutationComparisonVariant[];
-    sequenceType: SequenceType;
-    views: View[];
-    render(): JSX_2.Element;
+declare interface Mutation {
+    readonly segment: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    equals(other: Mutation): boolean;
+    toString(): string;
 }
 
-declare interface MutationComparisonVariant {
-    lapisFilter: LapisFilter;
-    displayName: string;
+/**
+ * This component allows to compare mutations between different variants.
+ * A variant is defined by its LAPIS filter.
+ *
+ * It only shows substitutions and deletions, it does not show insertions.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * The table view shows mutations
+ * and the proportions with which the mutation occurs in the respective variant.
+ * It only shows mutations that are present in at least one of the variants
+ * and where the proportion is within the selected proportion interval for at least one variant.
+ *
+ * ### Venn View
+ *
+ * The Venn view shows the overlap of mutations between the variants in a Venn diagram.
+ * A variant is considered to have a certain mutation,
+ * if the proportion of the mutation in the variant is within the selected proportion interval.
+ * Thus, changing the proportion interval may change a mutations from being "common" between variant
+ * to being "for one variant only".
+ */
+export declare class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * An array of variants to compare.
+     *
+     * The `lapisFilter` will be sent as is to LAPIS to filter the mutation data.
+     * It must be a valid LAPIS filter object.
+     *
+     * The `displayName` will be used as the label for the variant in the views.
+     * It should be human-readable.
+     */
+    variants: {
+        lapisFilter: Record<string, string | number | null | boolean>;
+        displayName: string;
+    }[];
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
+    sequenceType: 'nucleotide' | 'amino acid';
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    views: ('table' | 'venn')[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
+    render(): JSX_2.Element;
 }
 
 /**
@@ -98,13 +231,26 @@ declare interface MutationComparisonVariant {
  * @fires {CustomEvent<SelectedMutationFilterStrings>} gs-mutation-filter-on-blur - When the mutation filter has lost focus
  */
 export declare class MutationFilterComponent extends PreactLitAdapter {
+    initialValue: SelectedMutationFilterStrings | string[] | undefined;
     render(): JSX_2.Element;
 }
 
 export declare class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     variant: LapisFilter;
     sequenceType: SequenceType;
-    views: View_2[];
+    views: View[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
     render(): JSX_2.Element;
 }
 
@@ -124,13 +270,51 @@ declare abstract class PreactLitAdapterWithGridJsStyles extends PreactLitAdapter
     static styles: CSSResult[];
 }
 
+declare type PresetOptionValues = keyof typeof presets;
+
+declare const presets: {
+    custom: {
+        label: string;
+    };
+    allTimes: {
+        label: string;
+    };
+    last2Weeks: {
+        label: string;
+    };
+    lastMonth: {
+        label: string;
+    };
+    last2Months: {
+        label: string;
+    };
+    last3Months: {
+        label: string;
+    };
+    last6Months: {
+        label: string;
+    };
+};
+
 export declare class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
     numerator: NamedLapisFilter | NamedLapisFilter[];
     denominator: NamedLapisFilter;
     granularity: TemporalGranularity;
     smoothingWindow: number;
-    views: View_3[];
+    views: View_2[];
     confidenceIntervalMethods: ConfidenceIntervalMethod[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
     render(): JSX_2.Element;
 }
 
@@ -181,30 +365,66 @@ export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
     numerator: LapisFilter;
     denominator: LapisFilter;
     generationTime: number;
-    views: View_4[];
+    views: View_3[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
     render(): JSX_2.Element;
 }
 
+declare type SelectedFilters = {
+    nucleotideMutations: (Substitution | Deletion)[];
+    aminoAcidMutations: (Substitution | Deletion)[];
+    nucleotideInsertions: Insertion[];
+    aminoAcidInsertions: Insertion[];
+};
+
+declare type SelectedMutationFilterStrings = {
+    [Key in keyof SelectedFilters]: string[];
+};
+
 declare type SequenceType = 'nucleotide' | 'amino acid';
 
+declare class Substitution implements Mutation {
+    readonly segment: string | undefined;
+    readonly valueAtReference: string | undefined;
+    readonly substitutionValue: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    constructor(segment: string | undefined, valueAtReference: string | undefined, substitutionValue: string | undefined, position: number);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Substitution | null;
+}
+
 declare type TemporalGranularity = 'day' | 'week' | 'month' | 'year';
 
 /**
  * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed - When the text input has changed
  */
 export declare class TextInputComponent extends PreactLitAdapter {
+    initialValue: string | undefined;
     lapisField: string;
-    placeholderText: string;
+    placeholderText: string | undefined;
     render(): JSX_2.Element;
 }
 
-declare type View = 'table' | 'venn';
+declare type View = 'table' | 'grid' | 'insertions';
 
-declare type View_2 = 'table' | 'grid' | 'insertions';
+declare type View_2 = 'bar' | 'line' | 'bubble' | 'table';
 
-declare type View_3 = 'bar' | 'line' | 'bubble' | 'table';
+declare type View_3 = 'line';
 
-declare type View_4 = 'line';
+declare type View_4 = 'table';
 
 export { }
 
@@ -218,72 +438,79 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-selector': DateRangeSelectorComponent;
-    }
-    interface HTMLElementEventMap {
-        'gs-date-range-changed': CustomEvent<{
-            dateFrom: string;
-            dateTo: string;
-        }>;
+        'gs-mutation-comparison-component': MutationComparisonComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutation-filter': TextInputComponent;
-    }
-    interface HTMLElementEventMap {
-        'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;
-        'gs-mutation-filter-on-blur': CustomEvent<SelectedMutationFilterStrings>;
+        'gs-mutations-component': MutationsComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-text-input': TextInputComponent;
-    }
-    interface HTMLElementEventMap {
-        'gs-text-input-changed': CustomEvent<Record<string, string>>;
+        'gs-prevalence-over-time': PrevalenceOverTimeComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-location-filter': LocationFilterComponent;
+        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
     }
-    interface HTMLElementEventMap {
-        'gs-location-changed': CustomEvent<Record<string, string>>;
+}
+
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-aggregate-component': AggregateComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutation-comparison-component': MutationComparisonComponent;
+        'gs-date-range-selector': DateRangeSelectorComponent<string>;
+    }
+    interface HTMLElementEventMap {
+        'gs-date-range-changed': CustomEvent<{
+            dateFrom: string;
+            dateTo: string;
+        }>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutations-component': MutationsComponent;
+        'gs-location-filter': LocationFilterComponent;
+    }
+    interface HTMLElementEventMap {
+        'gs-location-changed': CustomEvent<Record<string, string>>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-prevalence-over-time': PrevalenceOverTimeComponent;
+        'gs-text-input': TextInputComponent;
+    }
+    interface HTMLElementEventMap {
+        'gs-text-input-changed': CustomEvent<Record<string, string>>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
+        'gs-mutation-filter': TextInputComponent;
+    }
+    interface HTMLElementEventMap {
+        'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;
+        'gs-mutation-filter-on-blur': CustomEvent<SelectedMutationFilterStrings>;
     }
 }