@genspectrum/dashboard-components 0.2.0 → 0.3.0

package/src/query/queryPrevalenceOverTime.ts

@@ -23,7 +23,7 @@ export type PrevalenceOverTimeVariantData = {
 
 export function queryPrevalenceOverTime(
     numeratorFilter: NamedLapisFilter | NamedLapisFilter[],
-    denominatorFilter: NamedLapisFilter,
+    denominatorFilter: LapisFilter,
     granularity: TemporalGranularity,
     smoothingWindow: number,
     lapis: string,
@@ -31,10 +31,10 @@ export function queryPrevalenceOverTime(
 ): Promise<PrevalenceOverTimeData> {
     const numeratorFilters = makeArray(numeratorFilter);
 
-    const denominatorData = fetchAndPrepare(getFilter(denominatorFilter), granularity, smoothingWindow);
+    const denominatorData = fetchAndPrepare(denominatorFilter, granularity, smoothingWindow);
     const subQueries = numeratorFilters.map(async (namedLapisFilter) => {
-        const { displayName, ...filter } = namedLapisFilter;
-        const numeratorData = fetchAndPrepare(filter, granularity, smoothingWindow);
+        const { displayName, lapisFilter } = namedLapisFilter;
+        const numeratorData = fetchAndPrepare(lapisFilter, granularity, smoothingWindow);
         const divide = new DivisionOperator(
             numeratorData,
             denominatorData,
@@ -53,12 +53,6 @@ export function queryPrevalenceOverTime(
     return Promise.all(subQueries);
 }
 
-function getFilter(filter: NamedLapisFilter) {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { displayName, ...filterWithoutDisplayName } = filter;
-    return filterWithoutDisplayName;
-}
-
 function makeArray<T>(arrayOrSingleItem: T | T[]) {
     if (Array.isArray(arrayOrSingleItem)) {
         return arrayOrSingleItem;

package/src/types.ts

@@ -2,7 +2,10 @@ import { type Deletion, type Insertion, type Substitution } from './utils/mutati
 
 export type LapisFilter = Record<string, string | number | null | boolean>;
 
-export type NamedLapisFilter = LapisFilter & { displayName: string };
+export type NamedLapisFilter = {
+    lapisFilter: LapisFilter;
+    displayName: string;
+};
 
 export type TemporalGranularity = 'day' | 'week' | 'month' | 'year';
 

package/src/web-components/ResizeContainer.mdx

@@ -0,0 +1,13 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Components/Size of components' />
+
+# Size of components
+
+All visualization and input components can be provided with a width prop (or height, when applicable) to control the size of the component.
+If not provided, the default width or height is used. In most cases, the default is a width of '100%' of its parent container and a predefined height.
+
+Both width and height can be set using the css units (e.g. 'px', 'em', 'rem', '%', 'vh', 'vw', etc.).
+By using '%', the size of the component can be controlled by the parent component.
+
+Caution: When using '%' as a unit, the parent component should have a defined width or height.

package/src/web-components/app.ts

@@ -27,6 +27,8 @@ import { fetchReferenceGenome } from '../lapisApi/lapisApi';
 @customElement('gs-app')
 export class App extends LitElement {
     /**
+     * Required.
+     *
      * The URL of the LAPIS instance that all children of this component will use.
      */
     @provide({ context: lapisContext })
@@ -54,7 +56,7 @@ export class App extends LitElement {
 
     override render() {
         return this.updateReferenceGenome.render({
-            complete: () => html` <slot></slot>`,
+            complete: () => html``, // Children will be rendered in the light DOM anyway. We can't use slots without a shadow DOM.
             error: () =>
                 html` <div class="m-2 w-full alert alert-error">
                     Error: Cannot fetch reference genome. Is LAPIS available?

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

@@ -26,9 +26,10 @@ const codeExample = String.raw`
     earliestDate="1970-01-01"
     initialValue="${PRESET_VALUE_LAST_6_MONTHS}"
     width="100%"
+    dateColumn="myDateColumn"
 ></gs-date-range-selector>`;
 
-const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
+const meta: Meta<Required<DateRangeSelectorProps<'CustomDateRange'>>> = {
     title: 'Input/DateRangeSelector',
     component: 'gs-date-range-selector',
     parameters: withComponentDocs({
@@ -58,6 +59,7 @@ const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
                 'CustomDateRange',
             ],
         },
+        dateColumn: { control: { type: 'text' } },
         customSelectOptions: {
             control: {
                 type: 'object',
@@ -78,6 +80,7 @@ const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
         customSelectOptions: [{ label: 'CustomDateRange', dateFrom: '2021-01-01', dateTo: '2021-12-31' }],
         earliestDate: '1970-01-01',
         initialValue: PRESET_VALUE_LAST_6_MONTHS,
+        dateColumn: 'aDateColumn',
         width: '100%',
     },
     decorators: [withActions],
@@ -86,7 +89,7 @@ const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
 
 export default meta;
 
-export const DateRangeSelectorStory: StoryObj<DateRangeSelectorProps<'CustomDateRange'>> = {
+export const DateRangeSelectorStory: StoryObj<Required<DateRangeSelectorProps<'CustomDateRange'>>> = {
     render: (args) =>
         html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
@@ -95,6 +98,7 @@ export const DateRangeSelectorStory: StoryObj<DateRangeSelectorProps<'CustomDate
                     .earliestDate=${args.earliestDate}
                     .initialValue=${args.initialValue}
                     .width=${args.width}
+                    .dateColumn=${args.dateColumn}
                 ></gs-date-range-selector>
             </div>
         </gs-app>`,
@@ -108,5 +112,9 @@ export const DateRangeSelectorStory: StoryObj<DateRangeSelectorProps<'CustomDate
                 expect(dateTo()).toHaveValue(toYYYYMMDD(new Date()));
             });
         });
+
+        // Due to the limitations of storybook testing which does not fire an event,
+        // when selecting a value from the dropdown we can't test the fired event here.
+        // An e2e test (using playwright) for that can be found in tests/dateRangeSelector.spec.ts
     },
 };

package/src/web-components/input/gs-date-range-selector.tsx

@@ -10,7 +10,8 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
  * ## 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,
@@ -20,12 +21,21 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
  * 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.
  */
 @customElement('gs-date-range-selector')
 export class DateRangeSelectorComponent extends PreactLitAdapter {
@@ -42,7 +52,7 @@ export class DateRangeSelectorComponent extends PreactLitAdapter {
      * The `dateFrom` value to use in the `allTimes` preset in the format `YYYY-MM-DD`.
      */
     @property({ type: String })
-    earliestDate: string | undefined = '1900-01-01';
+    earliestDate: string = '1900-01-01';
 
     // prettier-ignore
     // The multiline union type must not start with `| 'custom'` - Storybook will list "" as the first type which is wrong
@@ -61,19 +71,21 @@ export class DateRangeSelectorComponent extends PreactLitAdapter {
         | 'last2Months'
         | 'last3Months'
         | 'last6Months'
-        | string
-        | undefined = 'last6Months';
+        | string = 'last6Months';
 
     /**
      * 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.
      */
-    @property({ type: Object })
-    width: string | undefined = undefined;
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * The name of the column in LAPIS that contains the date information.
+     */
+    @property({ type: String })
+    dateColumn: string = 'date';
 
     override render() {
         return (
@@ -81,6 +93,7 @@ export class DateRangeSelectorComponent extends PreactLitAdapter {
                 customSelectOptions={this.customSelectOptions}
                 earliestDate={this.earliestDate}
                 initialValue={this.initialValue}
+                dateColumn={this.dateColumn}
                 width={this.width}
             />
         );
@@ -93,10 +106,7 @@ declare global {
     }
 
     interface HTMLElementEventMap {
-        'gs-date-range-changed': CustomEvent<{
-            dateFrom: string;
-            dateTo: string;
-        }>;
+        'gs-date-range-changed': CustomEvent<Record<string, string>>;
     }
 }
 
@@ -105,6 +115,6 @@ type CustomSelectOptionsMatches = Expect<
     Equals<typeof DateRangeSelectorComponent.prototype.customSelectOptions, CustomSelectOption<string>[]>
 >;
 type InitialValueMatches = Expect<
-    Equals<typeof DateRangeSelectorComponent.prototype.initialValue, PresetOptionValues | string | undefined>
+    Equals<typeof DateRangeSelectorComponent.prototype.initialValue, PresetOptionValues | string>
 >;
 /* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

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

@@ -14,8 +14,8 @@ import { withinShadowRoot } from '../withinShadowRoot.story';
 
 const codeExample = String.raw`
 <gs-location-filter
-    fields="['region', 'country']"
-    value='Europe / Switzerland'
+    fields='["region", "country"]'
+    initialValue='Europe / Switzerland'
     width="100%"
 ></gs-location-filter>`;
 
@@ -134,7 +134,9 @@ export const FetchingLocationsFails: StoryObj<LocationFilterProps> = {
                     matcher: aggregatedEndpointMatcher,
                     response: {
                         status: 400,
-                        body: { error: 'no data' },
+                        body: {
+                            error: { status: 400, detail: 'Dummy error message from mock LAPIS', type: 'about:blank' },
+                        },
                     },
                 },
             ],

package/src/web-components/input/gs-location-filter.tsx

@@ -40,6 +40,8 @@ export class LocationFilterComponent extends PreactLitAdapter {
     initialValue = '';
 
     /**
+     * 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
@@ -51,13 +53,10 @@ export 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.
      */
-    @property({ type: Object })
-    width: string | undefined = undefined;
+    @property({ type: String })
+    width: string = '100%';
 
     override render() {
         return <LocationFilter initialValue={this.initialValue} fields={this.fields} width={this.width} />;

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

@@ -13,7 +13,8 @@ import './gs-mutation-filter';
 const codeExample = String.raw`
 <gs-mutation-filter 
     initialValue='["A123T"]'
-    size='{ "width": "100%", "height": "6.5rem" }'
+    width='100%'
+    height='6.5rem'
 ></gs-mutation-filter>`;
 
 const meta: Meta<MutationFilterProps> = {
@@ -36,11 +37,8 @@ const meta: Meta<MutationFilterProps> = {
                 type: 'object',
             },
         },
-        size: {
-            control: {
-                type: 'object',
-            },
-        },
+        width: { control: 'text' },
+        height: { control: 'text' },
     },
     decorators: [withActions],
     tags: ['autodocs'],
@@ -52,13 +50,18 @@ const Template: StoryObj<MutationFilterProps> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
-                <gs-mutation-filter .initialValue=${args.initialValue} .size=${args.size}></gs-mutation-filter>
+                <gs-mutation-filter
+                    .initialValue=${args.initialValue}
+                    .width=${args.width}
+                    .height=${args.height}
+                ></gs-mutation-filter>
             </div>
         </gs-app>`;
     },
     args: {
         initialValue: [],
-        size: { width: '100%', height: '3rem' },
+        width: '100%',
+        height: '3rem',
     },
 };
 

package/src/web-components/input/gs-mutation-filter.tsx

@@ -18,22 +18,30 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
  * 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[],
@@ -61,36 +69,40 @@ export class MutationFilterComponent extends PreactLitAdapter {
     // The multiline union type must not start with `|` because it looks weird in the Storybook docs
     /**
      * 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.
      */
     @property()
     initialValue:
         {
-              nucleotideMutations: string[];
-              aminoAcidMutations: string[];
-              nucleotideInsertions: string[];
-              aminoAcidInsertions: string[];
-          }
+            nucleotideMutations: string[];
+            aminoAcidMutations: string[];
+            nucleotideInsertions: string[];
+            aminoAcidInsertions: string[];
+        }
         | string[]
         | undefined = 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.
+     */
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * 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.
      */
-    @property({ type: Object })
-    size: { width?: string; height?: string } | undefined = undefined;
+    @property({ type: String })
+    height: string = '6.5rem';
 
     override render() {
         return (
             <ReferenceGenomesAwaiter>
-                <MutationFilter initialValue={this.initialValue} size={this.size} />
+                <MutationFilter initialValue={this.initialValue} width={this.width} height={this.height} />
             </ReferenceGenomesAwaiter>
         );
     }

package/src/web-components/input/gs-text-input.stories.ts

@@ -19,7 +19,7 @@ const codeExample = String.raw`
     width="50%">
 </gs-text-input>`;
 
-const meta: Meta<TextInputProps> = {
+const meta: Meta<Required<TextInputProps>> = {
     title: 'Input/Text input',
     component: 'gs-text-input',
     parameters: withComponentDocs({
@@ -77,7 +77,7 @@ const meta: Meta<TextInputProps> = {
 
 export default meta;
 
-export const Default: StoryObj<TextInputProps> = {
+export const Default: StoryObj<Required<TextInputProps>> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
@@ -98,7 +98,7 @@ export const Default: StoryObj<TextInputProps> = {
     },
 };
 
-export const FiresEvent: StoryObj<TextInputProps> = {
+export const FiresEvent: StoryObj<Required<TextInputProps>> = {
     ...Default,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-text-input');

package/src/web-components/input/gs-text-input.tsx

@@ -7,7 +7,7 @@ import { PreactLitAdapter } from '../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.
@@ -25,10 +25,13 @@ export class TextInputComponent extends PreactLitAdapter {
      * The initial value to use for this text input.
      */
     @property()
-    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.
      */
     @property()
     lapisField = '';
@@ -37,18 +40,15 @@ export class TextInputComponent extends PreactLitAdapter {
      * The placeholder text to display in the input field.
      */
     @property()
-    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.
      */
-    @property({ type: Object })
-    width: string | undefined = undefined;
+    @property({ type: String })
+    width: string = '100%';
 
     override render() {
         return (

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

@@ -0,0 +1,11 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Input/Introduction' />
+
+# Introduction
+
+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.

package/src/web-components/introduction.mdx

@@ -0,0 +1,15 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title='Introduction' />
+
+# Introduction
+
+This package provides a collection of web components to build interactive dashboards that visualize
+data of a specific instance of [LAPIS](https://github.com/GenSpectrum/LAPIS).
+
+We primarily provide two kinds of components:
+
+-   Visualization components (charts, tables, etc.).
+    Those components fetch data from the LAPIS instance and visualize it.
+-   Input components that let you specify sequence filters for the LAPIS requests.
+    Input changes will fire events that can be listened to by the visualization components. It is the responsibility of the dashbaord maintainer to listen to those events and to wire the data correctly into the visualization components.

package/src/web-components/visualization/gs-aggregate.stories.ts

@@ -9,7 +9,17 @@ import type { AggregateProps } from '../../preact/aggregatedData/aggregate';
 import './gs-aggregate';
 import '../app';
 
-const meta: Meta<AggregateProps> = {
+const codeExample = `
+<gs-aggregate 
+    fields='["division", "host"]'
+    filter='{"country": "USA"}'
+    views='["table"]'
+    headline="Aggregate"
+    width='100%'
+    height='700px'
+></gs-aggregate>`;
+
+const meta: Meta<Required<AggregateProps>> = {
     title: 'Visualization/Aggregate',
     component: 'gs-aggregate',
     argTypes: {
@@ -18,7 +28,8 @@ const meta: Meta<AggregateProps> = {
             options: ['table'],
             control: { type: 'check' },
         },
-        size: [{ control: 'object' }],
+        width: { control: 'text' },
+        height: { control: 'text' },
         headline: { control: 'text' },
     },
     parameters: withComponentDocs({
@@ -43,7 +54,7 @@ const meta: Meta<AggregateProps> = {
         componentDocs: {
             opensShadowDom: true,
             expectsChildren: false,
-            codeExample: `<gs-aggregate fields='["division", "host"]' filter='{"country": "USA"}' views='["table"]'></gs-aggregate>`,
+            codeExample,
         },
     }),
     tags: ['autodocs'],
@@ -51,14 +62,15 @@ const meta: Meta<AggregateProps> = {
 
 export default meta;
 
-export const Table: StoryObj<AggregateProps> = {
+export const Table: StoryObj<Required<AggregateProps>> = {
     render: (args) => html`
         <gs-app lapis="${LAPIS_URL}">
             <gs-aggregate
                 .fields=${args.fields}
                 .filter=${args.filter}
                 .views=${args.views}
-                .size=${args.size}
+                .width=${args.width}
+                .height=${args.height}
                 .headline=${args.headline}
             ></gs-aggregate>
         </gs-app>
@@ -69,7 +81,8 @@ export const Table: StoryObj<AggregateProps> = {
         filter: {
             country: 'USA',
         },
-        size: { width: '100%', height: '700px' },
+        width: '100%',
+        height: '700px',
         headline: 'Aggregate',
     },
 };