@genspectrum/dashboard-components 0.19.8 → 0.20.0

package/dist/util.d.ts

@@ -77,38 +77,20 @@ export declare class DateRangeOptionChangedEvent extends CustomEvent<DateRangeVa
     constructor(detail: DateRangeValue);
 }
 
+declare type DateRangeOptionPresets = {
+    last2Weeks: DateRangeOption;
+    lastMonth: DateRangeOption;
+    last2Months: DateRangeOption;
+    last3Months: DateRangeOption;
+    last6Months: DateRangeOption;
+    lastYear: DateRangeOption;
+    allTimes: DateRangeOption;
+};
+
 /**
  * Presets for the `gs-date-range-filter` component that can be used as `dateRangeOptions`.
  */
-export declare const dateRangeOptionPresets: {
-    last2Weeks: {
-        label: string;
-        dateFrom: string;
-    };
-    lastMonth: {
-        label: string;
-        dateFrom: string;
-    };
-    last2Months: {
-        label: string;
-        dateFrom: string;
-    };
-    last3Months: {
-        label: string;
-        dateFrom: string;
-    };
-    last6Months: {
-        label: string;
-        dateFrom: string;
-    };
-    lastYear: {
-        label: string;
-        dateFrom: string;
-    };
-    allTimes: {
-        label: string;
-    };
-};
+export declare const dateRangeOptionPresets: () => DateRangeOptionPresets;
 
 /**
  * A date range option that can be used in the `gs-date-range-filter` component.
@@ -970,7 +952,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutations-component': MutationsComponent;
+        'gs-mutations': MutationsComponent;
     }
 }
 
@@ -978,7 +960,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-mutations-component': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-mutations': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1002,7 +984,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
+        'gs-aggregate': AggregateComponent;
     }
 }
 
@@ -1010,7 +992,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-relative-growth-advantage': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-aggregate': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1018,7 +1000,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-aggregate': AggregateComponent;
+        'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
     }
 }
 
@@ -1026,7 +1008,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-aggregate': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-relative-growth-advantage': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1034,7 +1016,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-number-sequences-over-time': NumberSequencesOverTimeComponent;
+        'gs-mutations-over-time': MutationsOverTimeComponent;
     }
 }
 
@@ -1042,7 +1024,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-number-sequences-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-mutations-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1050,7 +1032,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutations-over-time': MutationsOverTimeComponent;
+        'gs-number-sequences-over-time': NumberSequencesOverTimeComponent;
     }
 }
 
@@ -1058,7 +1040,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-mutations-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-number-sequences-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1082,11 +1064,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-filter': DateRangeFilterComponent;
-    }
-    interface HTMLElementEventMap {
-        [gsEventNames.dateRangeFilterChanged]: CustomEvent<Record<string, string>>;
-        [gsEventNames.dateRangeOptionChanged]: DateRangeOptionChangedEvent;
+        'gs-statistics': StatisticsComponent;
     }
 }
 
@@ -1094,7 +1072,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-date-range-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-statistics': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1102,10 +1080,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-location-filter': LocationFilterComponent;
-    }
-    interface HTMLElementEventMap {
-        [gsEventNames.locationChanged]: LocationChangedEvent;
+        'gs-wastewater-mutations-over-time': WastewaterMutationsOverTimeComponent;
     }
 }
 
@@ -1113,7 +1088,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-location-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-wastewater-mutations-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1121,7 +1096,11 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-statistics': StatisticsComponent;
+        'gs-date-range-filter': DateRangeFilterComponent;
+    }
+    interface HTMLElementEventMap {
+        [gsEventNames.dateRangeFilterChanged]: CustomEvent<Record<string, string>>;
+        [gsEventNames.dateRangeOptionChanged]: DateRangeOptionChangedEvent;
     }
 }
 
@@ -1129,7 +1108,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-statistics': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-date-range-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1137,10 +1116,10 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-text-filter': TextFilterComponent;
+        'gs-location-filter': LocationFilterComponent;
     }
     interface HTMLElementEventMap {
-        [gsEventNames.textFilterChanged]: TextFilterChangedEvent;
+        [gsEventNames.locationChanged]: LocationChangedEvent;
     }
 }
 
@@ -1148,7 +1127,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-text-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-location-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1156,10 +1135,10 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-lineage-filter': LineageFilterComponent;
+        'gs-text-filter': TextFilterComponent;
     }
     interface HTMLElementEventMap {
-        [gsEventNames.lineageFilterChanged]: LineageFilterChangedEvent;
+        [gsEventNames.textFilterChanged]: TextFilterChangedEvent;
     }
 }
 
@@ -1167,7 +1146,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-lineage-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-text-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1194,11 +1173,10 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-number-range-filter': NumberRangeFilterComponent;
+        'gs-lineage-filter': LineageFilterComponent;
     }
     interface HTMLElementEventMap {
-        [gsEventNames.numberRangeFilterChanged]: NumberRangeFilterChangedEvent;
-        [gsEventNames.numberRangeValueChanged]: NumberRangeValueChangedEvent;
+        [gsEventNames.lineageFilterChanged]: LineageFilterChangedEvent;
     }
 }
 
@@ -1206,7 +1184,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-number-range-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-lineage-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }
@@ -1214,7 +1192,11 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-wastewater-mutations-over-time': WastewaterMutationsOverTimeComponent;
+        'gs-number-range-filter': NumberRangeFilterComponent;
+    }
+    interface HTMLElementEventMap {
+        [gsEventNames.numberRangeFilterChanged]: NumberRangeFilterChangedEvent;
+        [gsEventNames.numberRangeValueChanged]: NumberRangeValueChangedEvent;
     }
 }
 
@@ -1222,7 +1204,7 @@ declare global {
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            'gs-wastewater-mutations-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-number-range-filter': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }

package/dist/util.js

@@ -1,4 +1,4 @@
-import { D, a, L, N, b, T, d, g, v } from "./NumberRangeFilterChangedEvent-RZ8haPHq.js";
+import { D, a, L, N, b, T, d, g, v } from "./NumberRangeFilterChangedEvent-RqWinxhE.js";
 export {
   D as DateRangeOptionChangedEvent,
   a as LineageFilterChangedEvent,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@genspectrum/dashboard-components",
-    "version": "0.19.8",
+    "version": "0.20.0",
     "description": "GenSpectrum web components for building dashboards",
     "type": "module",
     "license": "AGPL-3.0-only",

package/src/preact/dateRangeFilter/date-range-filter.stories.tsx

@@ -55,7 +55,7 @@ const meta: Meta<DateRangeFilterProps> = {
         },
     },
     args: {
-        dateRangeOptions: [dateRangeOptionPresets.lastMonth, dateRangeOptionPresets.allTimes, customDateRange],
+        dateRangeOptions: [dateRangeOptionPresets().lastMonth, dateRangeOptionPresets().allTimes, customDateRange],
         earliestDate,
         value: null,
         lapisDateField: 'aDateColumn',
@@ -150,7 +150,7 @@ export const SetsValueOnBlur: StoryObj<DateRangeFilterProps> = {
     ...Primary,
     args: {
         ...Primary.args,
-        value: dateRangeOptionPresets.lastMonth.label,
+        value: dateRangeOptionPresets().lastMonth.label,
     },
     play: async ({ canvasElement, step }) => {
         const { canvas, filterChangedListenerMock, optionChangedListenerMock } = await prepare(canvasElement, step);
@@ -211,7 +211,7 @@ export const ChangingTheValueProgrammatically: StoryObj<DateRangeFilterProps> =
                     <button className='btn' onClick={() => setValue(customDateRange.label)}>
                         Set to Custom
                     </button>
-                    <button className='btn' onClick={() => setValue(dateRangeOptionPresets.lastMonth.label)}>
+                    <button className='btn' onClick={() => setValue(dateRangeOptionPresets().lastMonth.label)}>
                         Set to Last month
                     </button>
                 </div>

package/src/preact/dateRangeFilter/dateRangeOption.ts

@@ -45,55 +45,81 @@ export class DateRangeOptionChangedEvent extends CustomEvent<DateRangeValue> {
     }
 }
 
-const today = new Date();
+type DateRangeOptionPresets = {
+    last2Weeks: DateRangeOption;
+    lastMonth: DateRangeOption;
+    last2Months: DateRangeOption;
+    last3Months: DateRangeOption;
+    last6Months: DateRangeOption;
+    lastYear: DateRangeOption;
+    allTimes: DateRangeOption;
+};
 
-const twoWeeksAgo = new Date();
-twoWeeksAgo.setDate(today.getDate() - 14);
+let dateRangeOptionsPresetsCacheDate: string | null = null;
+let dateRangeOptionPresetsCache: DateRangeOptionPresets | null = null;
 
-const lastMonth = new Date(today);
-lastMonth.setMonth(today.getMonth() - 1);
+/**
+ * Presets for the `gs-date-range-filter` component that can be used as `dateRangeOptions`.
+ */
+export const dateRangeOptionPresets = (): DateRangeOptionPresets => {
+    const today = new Date();
+    const todayString = new Date().toISOString().slice(0, 10);
 
-const last2Months = new Date(today);
-last2Months.setMonth(today.getMonth() - 2);
+    if (
+        dateRangeOptionPresetsCache === null ||
+        dateRangeOptionsPresetsCacheDate === null ||
+        dateRangeOptionsPresetsCacheDate !== todayString
+    ) {
+        dateRangeOptionsPresetsCacheDate = todayString;
 
-const last3Months = new Date(today);
-last3Months.setMonth(today.getMonth() - 3);
+        const twoWeeksAgo = new Date();
+        twoWeeksAgo.setDate(today.getDate() - 14);
 
-const last6Months = new Date(today);
-last6Months.setMonth(today.getMonth() - 6);
+        const lastMonth = new Date(today);
+        lastMonth.setMonth(today.getMonth() - 1);
 
-const lastYear = new Date(today);
-lastYear.setFullYear(today.getFullYear() - 1);
+        const last2Months = new Date(today);
+        last2Months.setMonth(today.getMonth() - 2);
 
-/**
- * Presets for the `gs-date-range-filter` component that can be used as `dateRangeOptions`.
- */
-export const dateRangeOptionPresets = {
-    last2Weeks: {
-        label: 'Last 2 weeks',
-        dateFrom: toYYYYMMDD(twoWeeksAgo),
-    },
-    lastMonth: {
-        label: 'Last month',
-        dateFrom: toYYYYMMDD(lastMonth),
-    },
-    last2Months: {
-        label: 'Last 2 months',
-        dateFrom: toYYYYMMDD(last2Months),
-    },
-    last3Months: {
-        label: 'Last 3 months',
-        dateFrom: toYYYYMMDD(last3Months),
-    },
-    last6Months: {
-        label: 'Last 6 months',
-        dateFrom: toYYYYMMDD(last6Months),
-    },
-    lastYear: {
-        label: 'Last year',
-        dateFrom: toYYYYMMDD(lastYear),
-    },
-    allTimes: {
-        label: 'All times',
-    },
-} satisfies Record<string, DateRangeOption>;
+        const last3Months = new Date(today);
+        last3Months.setMonth(today.getMonth() - 3);
+
+        const last6Months = new Date(today);
+        last6Months.setMonth(today.getMonth() - 6);
+
+        const lastYear = new Date(today);
+        lastYear.setFullYear(today.getFullYear() - 1);
+
+        dateRangeOptionPresetsCache = {
+            last2Weeks: {
+                label: 'Last 2 weeks',
+                dateFrom: toYYYYMMDD(twoWeeksAgo),
+            },
+            lastMonth: {
+                label: 'Last month',
+                dateFrom: toYYYYMMDD(lastMonth),
+            },
+            last2Months: {
+                label: 'Last 2 months',
+                dateFrom: toYYYYMMDD(last2Months),
+            },
+            last3Months: {
+                label: 'Last 3 months',
+                dateFrom: toYYYYMMDD(last3Months),
+            },
+            last6Months: {
+                label: 'Last 6 months',
+                dateFrom: toYYYYMMDD(last6Months),
+            },
+            lastYear: {
+                label: 'Last year',
+                dateFrom: toYYYYMMDD(lastYear),
+            },
+            allTimes: {
+                label: 'All times',
+            },
+        };
+    }
+
+    return dateRangeOptionPresetsCache;
+};

package/src/web-components/input/gs-date-range-filter.stories.ts

@@ -59,14 +59,14 @@ const meta: Meta<Required<DateRangeFilterProps>> = {
     },
     args: {
         dateRangeOptions: [
-            dateRangeOptionPresets.lastMonth,
-            dateRangeOptionPresets.last3Months,
-            dateRangeOptionPresets.allTimes,
+            dateRangeOptionPresets().lastMonth,
+            dateRangeOptionPresets().last3Months,
+            dateRangeOptionPresets().allTimes,
             { label: '2021', dateFrom: '2021-01-01', dateTo: '2021-12-31' },
             customDateRange,
         ],
         earliestDate: '1970-01-01',
-        value: dateRangeOptionPresets.lastMonth.label,
+        value: dateRangeOptionPresets().lastMonth.label,
         lapisDateField: 'aDateColumn',
         width: '100%',
         placeholder: 'Date range',

package/src/web-components/input/introduction.mdx

@@ -7,5 +7,60 @@ import { Meta } from '@storybook/blocks';
 The components in this section let the user specify values for LAPIS filters.
 The filters can then be used as input to the visualization components.
 
-Every component fires `CustomEvent`s when the user interacts with it, which can be used to update the LAPIS filters.
-The `detail` of the event is designed such that it can be directly passed to the LAPIS API.
+Every component fires `CustomEvent`s when the user interacts with it.
+`event.detail` contains the payload of the event.
+
+Every component fires an event that can be used to update the LAPIS filters.
+It is supposed to be used in the style of:
+
+```javascript
+component.addEventListener('gs-example-event', (event) => {
+    setNewLapisFilter({
+        ...previousLapisFilter,
+        ...event.detail,
+    });
+});
+```
+
+## Controlled Input Components
+
+HTML input components can be controlled or uncontrolled.
+In a controlled component, the value is controlled by surrounding Javascript code.
+In an uncontrolled component, the value is controlled by the DOM and the surrounding Javascript code only reads the value
+(e.g. by listening to events).
+
+All our input components can be used in both ways.
+Every component fires one or two events.
+If the event details can be used to update the LAPIS filter
+_and_ the value then the component will only fire one event,
+otherwise it will fire one event to update the LAPIS filter and one to update the value of the component.
+Refer to the documentation of the individual components for details on which event you can use for which purpose.
+
+**Example**: A controlled input component in a React app could conceptually look like this:
+
+```javascript
+import { useEffect, useRef, useState } from 'react';
+
+const ExampleInput = () => {
+    const [value, setValue] = useState('foo');
+    const inputRef = useRef(null);
+
+    useEffect(() => {
+        if (!inputRef.current) {
+            return;
+        }
+
+        const eventListener = (event) => {
+            setValue(event.detail);
+        };
+
+        inputRef.current.addEventListener('gs-input', eventListener);
+
+        return () => {
+            inputRef.current.removeEventListener('gs-input', eventListener);
+        };
+    }, []);
+
+    return <gs-example-input ref={inputRef} value={value} />;
+};
+```

package/src/web-components/tutorials/CreateYourFirstOwnDashboard.mdx

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Tutorials/Create your first own dashboard' />
+
+# Create your first own dashboard
+
+In this tutorial, you’ll learn how to integrate our `visualization` components into your HTML page.
+We’ll walk through building a simple dashboard that displays the number of sequences over time, along with some general statistics.
+This example serves as a foundation for your own dashboards—you can easily extend it by adding more components as needed.
+The data for these components must be provided by a LAPIS instance.
+For this tutorial, we’ll use one of our own [LAPIS](https://lapis.cov-spectrum.org/open/v2/docs/) instances, but you’re free to use any LAPIS instance that supplies the required data.
+
+## Create your HTML page
+
+Let's start by creating a simple HTML page. If you already have one, you can skip this step.
+Name the file `index.html` and add the following code. This will be the main file for your dashboard.
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My dashboard</title>
+    </head>
+    <body>
+        We will fill this section later
+    </body>
+</html>
+```
+
+## Include the dashboard components
+
+To use the components, you need to include the dashboard bundle in your HTML file.
+Add the following code to the `head` section:
+
+```html
+<script
+    type="module"
+    src="https://unpkg.com/@genspectrum/dashboard-components@latest/standalone-bundle/dashboard-components.js"
+></script>
+```
+
+This approach uses a standalone bundle, which includes all the code for the components in a single step.
+It is the easiest way to get started, although the bundle size is larger.
+Alternatively, you can use the components as modules, but this requires a build step.
+For more information, see the "Use the Components with Plain JavaScript" tutorial.
+
+## Add the dashboard components to your HTML file
+
+We are now ready to add the components to our HTML file.
+You can do this by adding the following code to the `body` section of your HTML file:
+
+```html
+<gs-app lapis="https://lapis.genspectrum.org/open/v2">
+    <h2>Statistics</h2>
+    <gs-statistics numeratorFilter='{"pangoLineage": "EG*"}' denominatorFilter="{}" width="100%"></gs-statistics>
+    <h2>Number of sequences over time</h2>
+    <gs-number-sequences-over-time
+        lapisFilters='[{ "displayName": "EG", "lapisFilter": { "pangoLineage": "EG*" } }]'
+        lapisDateField="date"
+        views='["bar", "line", "table"]'
+        width="100%"
+        granularity="month"
+        smoothingWindow="0"
+        pageSize="10"
+    ></gs-number-sequences-over-time>
+</gs-app>
+```
+
+Here, we are using three components:
+
+- `gs-app`: This is the main component that wraps all the other components. It is used to provide the context for the other components. Each of our components needs to be wrapped in this component.
+  It provides the `lapis` attribute, which is the URL of the LAPIS server. This is the server that provides the data for the components. In this example, we are using the LAPIS server for open SARS-CoV-2 data.
+- `gs-statistics` and `gs-number-sequences-over-time`: Visualization components that display data from the LAPIS server.
+
+You can find more examples and detailed descriptions of each component in our documentation.
+
+You now have your first dashboard. Open the `index.html` file in your browser to see it in action.
+Feel free to change some parameters to see how they affect the dashboard, or explore our Storybook for more examples.
+
+The parameters are currently fixed in the HTML file.
+If you want users to be able to change them—especially the filters—we also provide input components.
+To use them, add the input components to your HTML and connect them with JavaScript.
+For more information, see the "Use the Components with Plain JavaScript" tutorial.