@genspectrum/dashboard-components 0.1.5 → 0.3.0

package/dist/genspectrum-components.d.ts

@@ -10,43 +10,53 @@ import { TemplateResult } from 'lit-html';
 /**
  * ## Context
  *
- * This component displays aggregated data, which can provide an overview of the underlying data.
+ * This component displays aggregated data in a table, 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.
+ * It expects a list of `fields` to aggregate by and a `filter` to apply to the data.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * 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).
  */
 export declare class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     /**
      * The fields to aggregate by.
+     * Every field will be a table column.
+     * Every field must exist in the backing LAPIS instance.
+     *
+     * If left empty, the component will only show the absolute count of the provided `filter` and proportion `100%`.
      */
     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).
+     * A list of tabs with views that this component should provide.
      */
     views: View[];
     /**
      * The filter to apply to the data.
+     * It must be a valid LAPIS filter object.
      */
     filter: LapisFilter;
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
      *
-     * 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.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    size: {
-        width?: string;
-        height?: string;
-    } | undefined;
+    height: string;
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
-    headline: string | undefined;
+    headline: string;
     render(): JSX_2.Element;
 }
 
@@ -68,6 +78,8 @@ export declare class AggregateComponent extends PreactLitAdapterWithGridJsStyles
  */
 export declare class App extends LitElement {
     /**
+     * Required.
+     *
      * The URL of the LAPIS instance that all children of this component will use.
      */
     lapis: string;
@@ -79,7 +91,8 @@ export declare class App extends LitElement {
 
 /**
  * ## Context
- * This component is a group of input fields designed to specify a date range. It consists of 3 fields:
+ * This component is a group of input fields designed to specify date range filters
+ * for a given date column of this Lapis instance. It consists of 3 fields:
  *
  * - a select field to choose a predefined date range,
  * - an input field with an attached date picker for the start date,
@@ -89,12 +102,21 @@ export declare class App extends LitElement {
  * Setting a value in either of the date pickers will set the select field to "custom",
  * which represents an arbitrary date range.
  *
- * @fires {CustomEvent<{ dateFrom: string; dateTo: string; }>} gs-date-range-changed
+ * @fires {CustomEvent<{ `${dateColumn}From`: string; `${dateColumn}To`: string; }>} gs-date-range-changed
  * Fired when:
  * - The select field is changed,
  * - A date is selected in either of the date pickers,
  * - A date was typed into either of the date input fields, and the input field loses focus ("on blur").
  * Contains the dates in the format `YYYY-MM-DD`.
+ *
+ * Example: For `dateColumn = yourDate`, an event with `detail` containing
+ * ```
+ * {
+ *  yourDataFrom: "2021-01-01",
+ *  yourDataTo: "2021-12-31"
+ * }
+ *  ```
+ *  will be fired.
  */
 export declare class DateRangeSelectorComponent extends PreactLitAdapter {
     /**
@@ -111,39 +133,27 @@ export declare class DateRangeSelectorComponent extends PreactLitAdapter {
     /**
      * The `dateFrom` value to use in the `allTimes` preset in the format `YYYY-MM-DD`.
      */
-    earliestDate: string | undefined;
+    earliestDate: string;
     /**
      * The initial value to use for this date range selector.
      * Must be a valid label from the preset labels or a `label` given in the `customSelectOptions`.
      *
      * If the value is invalid, the component will default to `'last6Months'`.
      */
-    initialValue: 'custom' | 'allTimes' | 'last2Weeks' | 'lastMonth' | 'last2Months' | 'last3Months' | 'last6Months' | string | undefined;
+    initialValue: 'custom' | 'allTimes' | 'last2Weeks' | 'lastMonth' | 'last2Months' | 'last3Months' | 'last6Months' | string;
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The name of the column in LAPIS that contains the date information.
+     */
+    dateColumn: string;
     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>;
 
 /**
@@ -180,24 +190,26 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
      */
     initialValue: string;
     /**
+     * Required.
+     *
      * The fields to display in the location filter, in hierarchical order.
      * The top-level field should be the first entry in the array.
      * This component assumes that the values for each field form a strict hierarchy
      * (e.g., `fields = ['continent', 'country', 'city']`).
      */
     fields: string[];
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
     render(): JSX_2.Element;
 }
 
-declare interface Mutation {
-    readonly segment: string | undefined;
-    readonly position: number;
-    readonly code: string;
-    equals(other: Mutation): boolean;
-    toString(): string;
-}
-
 /**
+ * ## Context
+ *
  * This component allows to compare mutations between different variants.
  * A variant is defined by its LAPIS filter.
  *
@@ -222,6 +234,8 @@ declare interface Mutation {
  */
 export declare class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
     /**
+     * Required.
+     *
      * An array of variants to compare.
      *
      * The `lapisFilter` will be sent as is to LAPIS to filter the mutation data.
@@ -243,21 +257,21 @@ export declare class MutationComparisonComponent extends PreactLitAdapterWithGri
      */
     views: ('table' | 'venn')[];
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
      *
-     * 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.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    size: {
-        width?: string;
-        height?: string;
-    } | undefined;
+    height: string;
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
-    headline: string | undefined;
+    headline: string;
     render(): JSX_2.Element;
 }
 
@@ -270,22 +284,30 @@ export declare class MutationComparisonComponent extends PreactLitAdapterWithGri
  * All previously selected mutations are displayed at the input field and added to the event.
  * Users can remove a mutation by clicking the 'x' button next to the mutation.
  *
+ * ## Input Validation
+ *
  * Validation of the input is performed according to the following rules:
  *
+ * ### Mutations
+ *
  * Mutations have to conform to the following format: `<gene/segment>:<symbol at reference><position><Substituted symbol/Deletion>`
- *     - Gene/segment: The gene or segment where the mutation occurs. Must be contained in the reference genome
- *       (Optional for elements with only one gene/segment)
- *     - Symbol at reference: The symbol at the reference position. (Optional)
- *     - Position: The position of the mutation. (Required)
- *     - Substituted symbol/Deletion: The substituted symbol or '-' for a deletion. (Required)
- *     Example: S:614G, 614G, 614- or 614G
+ * - Gene/segment: The gene or segment where the mutation occurs. Must be contained in the reference genome.
+ *   (Optional for elements with only one gene/segment)
+ * - Symbol at reference: The symbol at the reference position. (Optional)
+ * - Position: The position of the mutation. (Required)
+ * - Substituted symbol/Deletion: The substituted symbol or '-' for a deletion. (Required)
+ *
+ * Examples: `S:614G`, `614G`, `614-`, `614G`
+ *
+ * ### Insertions
  *
  * Insertions have to conform to the following format: `ins_<gene/segment>:<position>:<Inserted symbols>`
- *     - Gene/segment: The gene or segment where the insertion occurs. Must be contained in the reference genome
- *       (Optional for elements with only one gene/segment)
- *     - Position: The position of the insertion. (Required)
- *     - Inserted symbols: The symbols that are inserted. (Required)
- *     Example: ins_S:614:G, ins_614:G
+ * - Gene/segment: The gene or segment where the insertion occurs. Must be contained in the reference genome.
+ *   (Optional for elements with only one gene/segment)
+ * - Position: The position of the insertion. (Required)
+ * - Inserted symbols: The symbols that are inserted. (Required)
+ *
+ * Examples: `ins_S:614:G`, `ins_614:G`
  *
  * @fires {CustomEvent<{
  *      nucleotideMutations: string[],
@@ -310,15 +332,33 @@ export declare class MutationComparisonComponent extends PreactLitAdapterWithGri
 export declare class MutationFilterComponent extends PreactLitAdapter {
     /**
      * The initial value to use for this mutation filter.
-     * Must be either
-     * - an array of strings of valid mutations.
-     * - an object with the keys `nucleotideMutations`, `aminoAcidMutations`, `nucleotideInsertions` and `aminoAcidInsertions` and corresponding string arrays.
+     * All values provided must be valid mutations or insertions.
+     * Invalid values will be ignored.
+     */
+    initialValue: {
+        nucleotideMutations: string[];
+        aminoAcidMutations: string[];
+        nucleotideInsertions: string[];
+        aminoAcidInsertions: string[];
+    } | string[] | undefined;
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    initialValue: SelectedMutationFilterStrings | string[] | undefined;
+    width: string;
+    /**
+     * The height of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    height: string;
     render(): JSX_2.Element;
 }
 
 /**
+ * ## Context
+ *
  * This component displays mutations (substitutions, deletions and insertions) for a given variant.
  *
  * ## Views
@@ -345,6 +385,8 @@ export declare class MutationFilterComponent extends PreactLitAdapter {
  */
 export declare class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     /**
+     * Required.
+     *
      * The `variant` will be sent as is to LAPIS to filter the mutation data.
      * It must be a valid LAPIS filter object.
      */
@@ -358,21 +400,21 @@ export declare class MutationsComponent extends PreactLitAdapterWithGridJsStyles
      */
     views: ('table' | 'grid' | 'insertions')[];
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
      *
-     * 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.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    size: {
-        width?: string;
-        height?: string;
-    } | undefined;
+    height: string;
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
-    headline: string | undefined;
+    headline: string;
     render(): JSX_2.Element;
 }
 
@@ -389,6 +431,8 @@ declare abstract class PreactLitAdapterWithGridJsStyles extends PreactLitAdapter
 }
 
 /**
+ * ## Context
+ *
  * This component displays the prevalence over time of one or more variants.
  * The prevalence is calculated as the ratio of the number of cases of each variant given as `numerator`
  * to the number of cases of the variant given as `denominator`.
@@ -425,22 +469,26 @@ declare abstract class PreactLitAdapterWithGridJsStyles extends PreactLitAdapter
  */
 export declare class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
     /**
+     *   Required.
+     *
      * Either a single variant or an array of variants to compare.
      * This must be a valid LAPIS filter object with an additional `displayName` property
      * which will be used as the label for the variant in the views,
      * or an array of such objects.
      */
-    numerator: (Record<string, string | number | null | boolean> & {
+    numerator: {
+        lapisFilter: Record<string, string | number | null | boolean>;
         displayName: string;
-    }) | (Record<string, string | number | null | boolean> & {
+    } | {
+        lapisFilter: Record<string, string | number | null | boolean>;
         displayName: string;
-    })[];
+    }[];
     /**
+     * Required.
+     *
      * The variant that the variants in `numerator` are compared to.
      */
-    denominator: Record<string, string | number | null | boolean> & {
-        displayName: string;
-    };
+    denominator: Record<string, string | number | null | boolean>;
     /**
      * The granularity of the time axis.
      */
@@ -468,19 +516,19 @@ export declare class PrevalenceOverTimeComponent extends PreactLitAdapterWithGri
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
-    headline: string | undefined;
+    headline: string;
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
      *
-     * 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.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    size: {
-        width?: string;
-        height?: string;
-    } | undefined;
+    height: string;
     render(): JSX_2.Element;
 }
 
@@ -528,7 +576,9 @@ declare const referenceGenomeResponse: default_2.ZodObject<{
 }>;
 
 /**
- * We assume a discrete time model, where new infections happen exactly every `generationTime` days.
+ * ## Context
+ *
+ * For this component, we assume a discrete time model, where new infections happen exactly every `generationTime` days.
  * This is what we call a "generation".
  *
  * This component estimates the relative growth advantage of a variant by performing a logistic regression.
@@ -553,10 +603,14 @@ declare const referenceGenomeResponse: default_2.ZodObject<{
  */
 export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
     /**
+     * Required.
+     *
      * The LAPIS filter for the focal variant.
      */
     numerator: Record<string, string | number | null | boolean>;
     /**
+     * Required.
+     *
      * The LAPIS filter for the variant that the focal variant (`numerator`) should be compared to.
      */
     denominator: Record<string, string | number | null | boolean>;
@@ -572,50 +626,27 @@ export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
     /**
      * The headline of the component. Set to an empty string to hide the headline.
      */
-    headline: string | undefined;
+    headline: string;
     /**
-     * The size of the component.
+     * The width of the component.
      *
-     * If not set, the component will take the full width of its container with height 700px.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
      *
-     * 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.
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
      */
-    size: {
-        width?: string;
-        height?: string;
-    } | undefined;
+    height: string;
     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 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;
-}
-
 /**
  *
  * ## Context
  *
- * This component provides a text input field to specify filters for arbitrary fields of this Lapis instance.
+ * This component provides a text input field to specify filters for arbitrary fields of this LAPIS instance.
  *
  * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed
  * Fired when the input field is changed.
@@ -631,15 +662,24 @@ export declare class TextInputComponent extends PreactLitAdapter {
     /**
      * The initial value to use for this text input.
      */
-    initialValue: string | undefined;
+    initialValue: string;
     /**
-     * The Lapis field name to use for this text input.
+     * Required.
+     *
+     * The LAPIS field name to use for this text input.
+     * The field must exist on this LAPIS instance.
      */
     lapisField: string;
     /**
      * The placeholder text to display in the input field.
      */
-    placeholderText: string | undefined;
+    placeholderText: string;
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboards/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
     render(): JSX_2.Element;
 }
 
@@ -695,10 +735,7 @@ declare global {
         'gs-date-range-selector': DateRangeSelectorComponent;
     }
     interface HTMLElementEventMap {
-        'gs-date-range-changed': CustomEvent<{
-            dateFrom: string;
-            dateTo: string;
-        }>;
+        'gs-date-range-changed': CustomEvent<Record<string, string>>;
     }
 }
 
@@ -725,7 +762,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutation-filter': TextInputComponent;
+        'gs-mutation-filter': MutationFilterComponent;
     }
     interface HTMLElementEventMap {
         'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;