@genspectrum/dashboard-components 0.2.0 → 0.3.1

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,23 +133,24 @@ 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.
      *
-     * If not set, the component will take the full width of its container.
-     *
-     * The width should be a string with a unit in css style, e.g. '100%', '500px' or '50vw'.
-     * 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.
      */
-    width: string | undefined;
+    width: string;
+    /**
+     * The name of the column in LAPIS that contains the date information.
+     */
+    dateColumn: string;
     render(): JSX_2.Element;
 }
 
@@ -148,7 +171,7 @@ declare type LapisFilter = Record<string, string | number | null | boolean>;
  * Values for the fields `i > K` are considered `undefined`.
  *
  * @fires {CustomEvent<Record<string, string>>} gs-location-changed
- * Fired when the field is submitted with a valid location value.
+ * Fired when a value from the datalist is selected or when a valid value is typed into the field.
  * The `details` of this event contain an object with all `fields` as keys
  * and the corresponding values as values, if they are not `undefined`.
  * Example:
@@ -167,6 +190,8 @@ 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
@@ -176,16 +201,15 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
     /**
      * The width of the component.
      *
-     * If not set, the component will take the full width of its container.
-     *
-     * The width should be a string with a unit in css style, e.g. '100%', '500px' or '50vw'.
-     * 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.
      */
-    width: string | undefined;
+    width: string;
     render(): JSX_2.Element;
 }
 
 /**
+ * ## Context
+ *
  * This component allows to compare mutations between different variants.
  * A variant is defined by its LAPIS filter.
  *
@@ -210,6 +234,8 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
  */
 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.
@@ -231,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;
 }
 
@@ -258,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[],
@@ -298,9 +332,8 @@ 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[];
@@ -309,21 +342,23 @@ export declare class MutationFilterComponent extends PreactLitAdapter {
         aminoAcidInsertions: string[];
     } | string[] | undefined;
     /**
-     * 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;
 }
 
 /**
+ * ## Context
+ *
  * This component displays mutations (substitutions, deletions and insertions) for a given variant.
  *
  * ## Views
@@ -350,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.
      */
@@ -363,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;
 }
 
@@ -394,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`.
@@ -430,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.
      */
@@ -473,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;
 }
 
@@ -533,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.
@@ -558,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>;
@@ -577,19 +626,19 @@ 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;
 }
 
@@ -597,7 +646,7 @@ export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
  *
  * ## 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.
@@ -613,24 +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.
      *
-     * If not set, the component will take the full width of its container.
-     *
-     * The width should be a string with a unit in css style, e.g. '100%', '500px' or '50vw'.
-     * 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.
      */
-    width: string | undefined;
+    width: string;
     render(): JSX_2.Element;
 }
 
@@ -669,37 +718,34 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-aggregate-component': AggregateComponent;
+        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
+        'gs-aggregate-component': AggregateComponent;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-selector': DateRangeSelectorComponent;
+        'gs-location-filter': LocationFilterComponent;
     }
     interface HTMLElementEventMap {
-        'gs-date-range-changed': CustomEvent<{
-            dateFrom: string;
-            dateTo: string;
-        }>;
+        'gs-location-changed': CustomEvent<Record<string, string>>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-location-filter': LocationFilterComponent;
+        'gs-date-range-selector': DateRangeSelectorComponent;
     }
     interface HTMLElementEventMap {
-        'gs-location-changed': CustomEvent<Record<string, string>>;
+        'gs-date-range-changed': CustomEvent<Record<string, string>>;
     }
 }