@genspectrum/dashboard-components 0.10.3 → 0.10.4

package/dist/components.d.ts

@@ -908,6 +908,159 @@ export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
     render(): JSX_2.Element;
 }
 
+/**
+ * ## Context
+ *
+ * This component shows the geographic distribution of sequence data from LAPIS.
+ * It displays the count and proportion (number of sample per `lapisLocationField` / number of samples matching the `lapisFilter`)
+ * of the data by location.
+ *
+ * ## Views
+ *
+ * ### Map View
+ *
+ * This view displays a chloropleth map based on [Leaflet](https://leafletjs.com/).
+ * The component expects a `mapSource` object that specifies where the map data can be downloaded from.
+ * We can imagine that we add other map source types later (for example, GeoJSON).
+ *
+ * #### TopoJSON
+ *
+ * Suppose you provide this example object as `mapSource`:
+ *
+ * ```json
+ * {
+ *    "type": "topojson",
+ *    "url": "https://example.com/map.topojson",
+ *    "topologyObjectsKey": "myObjectKey"
+ * }
+ * ```
+ *
+ * The URL must point to a [TopoJSON file](https://github.com/topojson/topojson) that contains the map data.
+ * The TopoJSON file must schematically look like this,
+ * where `objects[topologyObjectsKey]` must be a valid GeometryCollection (`objects.myObjectKey` in this example):
+ *
+ * ```json
+ * {
+ *   "type": "Topology",
+ *   "objects": {
+ *     "myObjectKey": {
+ *       "type": "GeometryCollection",
+ *       "geometries": [
+ *         {
+ *           "type": "Polygon",
+ *           "properties": {
+ *             "name": "North Rhine Westphalia"
+ *           },
+ *           "id": "DE.NW",
+ *           "arcs": [...]
+ *         },
+ *         ...
+ *       ]
+ *     }
+ *   },
+ *   "arcs": [...],
+ *   "transform": {...}
+ * }
+ * ```
+ *
+ * You can use any valid TopoJSON file.
+ * https://github.com/markmarkoh/datamaps/tree/master/src/js/data contains TopoJSON files for many countries.
+ *
+ * The `lapisFilter` is used to select the data to display, and it is aggregated by the `lapisLocationField`.
+ * This component assumes that every geometry object in the TopoJSON file has a `properties.name` field.
+ *
+ * The values that LAPIS returns for `lapisLocationField` must match the `properties.name` in the map data.
+ * LAPIS entries where `lapisLocationField` is `null` are ignored on the map.
+ *
+ * The names of the locations in the TopoJSON map and in LAPIS should match.
+ * However, there are two cases of misalignment:
+ * - If there is a LAPIS location that does not match any location in the TopoJSON map,
+ *   the component will log a console warning to assist in creating map data that aligns with the LAPIS data.
+ * - If a TopoJSON location does not match any LAPIS location for the given filter,
+ *   no data will be displayed for this location.
+ *   This is expected, as LAPIS will only return locations where sequences have been collected for that filter.
+ *
+ * ### Table View
+ *
+ * This view displays the data in a table format.
+ * It is similar to the table view of the `gs-aggregate` component.
+ * The table has three columns:
+ * - `lapisLocationField`,
+ * - `count` (the number of samples in this location matching the `lapisFilter`),
+ * - `proportion` (`count` / sum of the `count` of all locations).
+ */
+export declare class SequencesByLocationComponent extends PreactLitAdapterWithGridJsStyles {
+    static styles: CSSResult[];
+    /**
+     * LAPIS filter to select the displayed data.
+     * If you want to display the distribution over the states of a certain country,
+     * you should usually filter by that country here (e.g. { country: 'USA' }).
+     */
+    lapisFilter: Record<string, string | number | null | boolean>;
+    /**
+     * Required.
+     *
+     * The location field to aggregate the data by.
+     * This should match the selected map location granularity.
+     */
+    lapisLocationField: string;
+    /**
+     * Required when using the map view.
+     *
+     * The source of the map data. See component level docs for more information.
+     */
+    mapSource: {
+        type: 'topojson';
+        url: string;
+        topologyObjectsKey: string;
+    } | undefined;
+    /**
+     * Enable map navigation (dragging, keyboard navigation, zooming).
+     */
+    enableMapNavigation: boolean;
+    /**
+     * The width of the component.
+     * Not that the map in the map view is not responsive
+     * (i.e. does not adjust its size when the component is resized).
+     *
+     * Visit https://genspectrum.github.io/dashboard-components/?path=/docs/components-size-of-components--docs for more information.
+     */
+    width: string;
+    /**
+     * The height of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboard-components/?path=/docs/components-size-of-components--docs for more information.
+     */
+    height: string;
+    /**
+     A list of tabs with views that this component should provide.
+     */
+    views: ('map' | 'table')[];
+    /**
+     * The initial zoom level of the map.
+     */
+    zoom: number;
+    /**
+     * Initially shift the center of the map in x direction (longitude).
+     *
+     * `-180` is the International Date Line with the map shifted to the right, `0` is the prime meridian,
+     * `180` is the International Date Line with the map shifted to the left.
+     */
+    offsetX: number;
+    /**
+     * Initially shift the center of the map in y direction (latitude).
+     *
+     * `-90` is the South Pole, `0` is the equator, `90` is the North Pole.
+     */
+    offsetY: number;
+    /**
+     * The maximum number of rows to display in the table view.
+     * Set to `false` to disable pagination. Set to `true` to enable pagination with a default limit (10).
+     */
+    pageSize: boolean | number;
+    render(): JSX_2.Element;
+}
+
 /**
  * ## Context
  *
@@ -1080,6 +1233,22 @@ declare global {
 }
 
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-aggregate': AggregateComponent;
+    }
+}
+
+
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'gs-aggregate': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+        }
+    }
+}
+
+
 declare global {
     interface HTMLElementTagNameMap {
         'gs-number-sequences-over-time': NumberSequencesOverTimeComponent;
@@ -1098,7 +1267,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-aggregate': AggregateComponent;
+        'gs-sequences-by-location': SequencesByLocationComponent;
     }
 }
 
@@ -1106,7 +1275,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-aggregate': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-sequences-by-location': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1146,11 +1315,10 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-selector': DateRangeSelectorComponent;
+        'gs-location-filter': LocationFilterComponent;
     }
     interface HTMLElementEventMap {
-        'gs-date-range-filter-changed': CustomEvent<Record<string, string>>;
-        'gs-date-range-option-changed': DateRangeOptionChangedEvent;
+        'gs-location-changed': CustomEvent<Record<string, string>>;
     }
 }
 
@@ -1158,7 +1326,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-date-range-selector': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-location-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1166,10 +1334,11 @@ declare global {
 
 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-filter-changed': CustomEvent<Record<string, string>>;
+        'gs-date-range-option-changed': DateRangeOptionChangedEvent;
     }
 }
 
@@ -1177,7 +1346,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-location-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-date-range-selector': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }