@genspectrum/dashboard-components 0.1.3 → 0.1.5

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

@@ -1,21 +1,77 @@
 import { customElement, property } from 'lit/decorators.js';
 
-import { type CustomSelectOption, DateRangeSelector } from '../../preact/dateRangeSelector/date-range-selector';
+import {
+    type CustomSelectOption,
+    DateRangeSelector,
+    type PresetOptionValues,
+} from '../../preact/dateRangeSelector/date-range-selector';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<{ dateFrom: string; dateTo: string; }>} gs-date-range-changed - When the date range has changed
+ * ## Context
+ * This component is a group of input fields designed to specify a date range. 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,
+ * - an input field with an attached date picker for the end date.
+ *
+ * Setting a value in the select field will overwrite the previous values of the start and end date.
+ * 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
+ * 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`.
  */
 @customElement('gs-date-range-selector')
 export class DateRangeSelectorComponent extends PreactLitAdapter {
+    /**
+     * An array of custom options that the select field should provide,
+     * in addition to the predefined options.
+     * The `label` will be shown to the user, and it will be available as `initialValue`.
+     * The dates must be in the format `YYYY-MM-DD`.
+     */
     @property({ type: Array })
-    customSelectOptions: CustomSelectOption[] = [];
+    customSelectOptions: { label: string; dateFrom: string; dateTo: string }[] = [];
 
+    /**
+     * The `dateFrom` value to use in the `allTimes` preset in the format `YYYY-MM-DD`.
+     */
     @property({ type: String })
     earliestDate: string | undefined = '1900-01-01';
 
+    // prettier-ignore
+    // The multiline union type must not start with `| 'custom'` - Storybook will list "" as the first type which is wrong
+    /**
+     * 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'`.
+     */
+    @property()
+    initialValue:
+        'custom'
+        | 'allTimes'
+        | 'last2Weeks'
+        | 'lastMonth'
+        | 'last2Months'
+        | 'last3Months'
+        | 'last6Months'
+        | string
+        | undefined = 'last6Months';
+
     override render() {
-        return <DateRangeSelector customSelectOptions={this.customSelectOptions} earliestDate={this.earliestDate} />;
+        return (
+            <DateRangeSelector
+                customSelectOptions={this.customSelectOptions}
+                earliestDate={this.earliestDate}
+                initialValue={this.initialValue}
+            />
+        );
     }
 }
 
@@ -31,3 +87,12 @@ declare global {
         }>;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type CustomSelectOptionsMatches = Expect<
+    Equals<typeof DateRangeSelectorComponent.prototype.customSelectOptions, CustomSelectOption<string>[]>
+>;
+type InitialValueMatches = Expect<
+    Equals<typeof DateRangeSelectorComponent.prototype.initialValue, PresetOptionValues | string | undefined>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

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

@@ -4,6 +4,7 @@ import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import '../app';
 import './location-filter-component';
@@ -14,12 +15,19 @@ import { withinShadowRoot } from '../withinShadowRoot.story';
 const meta: Meta = {
     title: 'Input/Location filter',
     component: 'gs-location-filter',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-location-changed'],
         },
-    },
+        componentDocs: {
+            tag: 'gs-location-filter',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample: `<gs-location-filter fields="['continent', 'country']" value='Europe / Switzerland'></gs-location-filter>`,
+        },
+    }),
     decorators: [withActions],
+    tags: ['autodocs'],
 };
 
 export default meta;
@@ -28,13 +36,16 @@ const Template: StoryObj<LocationFilterProps> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
-                <gs-location-filter .fields=${args.fields} value=${ifDefined(args.value)}></gs-location-filter>
+                <gs-location-filter
+                    .fields=${args.fields}
+                    initialValue=${ifDefined(args.initialValue)}
+                ></gs-location-filter>
             </div>
         </gs-app>`;
     },
     args: {
         fields: ['region', 'country', 'division', 'location'],
-        value: '',
+        initialValue: '',
     },
 };
 

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

@@ -4,10 +4,6 @@ import { LocationFilter } from '../../preact/locationFilter/location-filter';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * ## Tag
- *
- * `gs-location-filter`
- *
  * ## Context
  *
  * This component provides an input field to specify filters for locations.
@@ -41,7 +37,7 @@ export class LocationFilterComponent extends PreactLitAdapter {
      * Must be of the form `valueForField1 / valueForField2 / ... / valueForFieldN`.
      */
     @property()
-    value = '';
+    initialValue = '';
 
     /**
      * The fields to display in the location filter, in hierarchical order.
@@ -53,7 +49,7 @@ export class LocationFilterComponent extends PreactLitAdapter {
     fields: string[] = [];
 
     override render() {
-        return <LocationFilter value={this.value} fields={this.fields} />;
+        return <LocationFilter initialValue={this.initialValue} fields={this.fields} />;
     }
 }
 

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

@@ -3,41 +3,62 @@ import { expect, fn, userEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL } from '../../constants';
 import '../app';
+import { type MutationFilterProps } from '../../preact/mutationFilter/mutation-filter';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 import './mutation-filter-component';
 
-const meta: Meta = {
+const codeExample = String.raw`<gs-mutation-filter initialValue='["A123T"]'></gs-mutation-filter>`;
+
+const meta: Meta<MutationFilterProps> = {
     title: 'Input/Mutation filter',
     component: 'gs-mutation-filter',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-mutation-filter-changed', 'gs-mutation-filter-on-blur'],
         },
         fetchMock: {},
-    },
+        componentDocs: {
+            tag: 'gs-mutation-filter',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
     decorators: [withActions],
+    tags: ['autodocs'],
 };
 
 export default meta;
 
-export const Default: StoryObj<{ lapisField: string; placeholderText: string }> = {
-    render: () => {
+const Template: StoryObj<MutationFilterProps> = {
+    render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
-                <gs-mutation-filter></gs-mutation-filter>
+                <gs-mutation-filter .initialValue=${args.initialValue}></gs-mutation-filter>
             </div>
         </gs-app>`;
     },
+    args: {
+        initialValue: [],
+    },
+};
+
+export const Default: StoryObj<MutationFilterProps> = {
+    ...Template,
+    args: {
+        initialValue: ['A123T'],
+    },
 };
 
-export const FiresFilterChangedEvent: StoryObj<{ lapisField: string; placeholderText: string }> = {
-    ...Default,
+export const FiresFilterChangedEvent: StoryObj<MutationFilterProps> = {
+    ...Template,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-filter');
 
-        const inputField = () => canvas.getByPlaceholderText('Enter a mutation');
+        const inputField = () => canvas.getByPlaceholderText('Enter a mutation', { exact: false });
         const submitButton = () => canvas.getByRole('button', { name: '+' });
         const listenerMock = fn();
         await step('Setup event listener mock', async () => {
@@ -70,12 +91,12 @@ export const FiresFilterChangedEvent: StoryObj<{ lapisField: string; placeholder
     },
 };
 
-export const FiresFilterOnBlurEvent: StoryObj<{ lapisField: string; placeholderText: string }> = {
-    ...Default,
+export const FiresFilterOnBlurEvent: StoryObj<MutationFilterProps> = {
+    ...Template,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-mutation-filter');
 
-        const inputField = () => canvas.getByPlaceholderText('Enter a mutation');
+        const inputField = () => canvas.getByPlaceholderText('Enter a mutation', { exact: false });
         const listenerMock = fn();
         await step('Setup event listener mock', async () => {
             canvasElement.addEventListener('gs-mutation-filter-on-blur', listenerMock);

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

@@ -1,17 +1,73 @@
-import { customElement } from 'lit/decorators.js';
+import { customElement, property } from 'lit/decorators.js';
 
 import { type TextInputComponent } from './text-input-component';
+import { ReferenceGenomesAwaiter } from '../../preact/components/ReferenceGenomesAwaiter';
 import { MutationFilter, type SelectedMutationFilterStrings } from '../../preact/mutationFilter/mutation-filter';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<SelectedMutationFilterStrings>} gs-mutation-filter-changed - When the mutation filter values have changed
- * @fires {CustomEvent<SelectedMutationFilterStrings>} gs-mutation-filter-on-blur - When the mutation filter has lost focus
+ * ## Context
+ * This component provides an input field to specify filters for nucleotide and amino acid mutations and insertions.
+ *
+ * Input values have to be provided one at a time and submitted by pressing the Enter key or by clicking the '+' button.
+ * After submission, the component validates the input and fires an event with the selected mutations.
+ * 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.
+ *
+ * Validation of the input is performed according to the following rules:
+ *
+ * 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
+ *
+ * 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
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-changed
+ * Fired when:
+ * - The user has submitted a valid mutation or insertion
+ * - The user has removed a mutation or insertion
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-on-blur
+ * Fired when:
+ * - the mutation filter has lost focus
+ * Contains the selected mutations in the format
  */
 @customElement('gs-mutation-filter')
 export 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.
+     */
+    @property()
+    initialValue: SelectedMutationFilterStrings | string[] | undefined = undefined;
+
     override render() {
-        return <MutationFilter />;
+        return (
+            <ReferenceGenomesAwaiter>
+                <MutationFilter initialValue={this.initialValue} />
+            </ReferenceGenomesAwaiter>
+        );
     }
 }
 

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

@@ -3,16 +3,21 @@ import { expect, fn, userEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import '../app';
 import './text-input-component';
 import data from '../../preact/textInput/__mockData__/aggregated_hosts.json';
+import type { TextInputProps } from '../../preact/textInput/text-input';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
-const meta: Meta = {
+const codeExample = String.raw`
+<gs-text-input lapisField="host" placeholderText="Enter host name" initialValue="Homo sapiens"></gs-text-input>`;
+
+const meta: Meta<TextInputProps> = {
     title: 'Input/Text input',
     component: 'gs-text-input',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-text-input-changed'],
         },
@@ -33,28 +38,39 @@ const meta: Meta = {
                 },
             ],
         },
-    },
+        componentDocs: {
+            tag: 'gs-text-input',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
     decorators: [withActions],
     tags: ['autodocs'],
 };
 
 export default meta;
 
-export const Default: StoryObj<{ lapisField: string; placeholderText: string }> = {
+export const Default: StoryObj<TextInputProps> = {
     render: (args) => {
         return html` <gs-app lapis="${LAPIS_URL}">
             <div class="max-w-screen-lg">
-                <gs-text-input .lapisField=${args.lapisField} .placeholderText=${args.placeholderText}></gs-text-input>
+                <gs-text-input
+                    .lapisField=${args.lapisField}
+                    .placeholderText=${args.placeholderText}
+                    .initialValue=${args.initialValue}
+                ></gs-text-input>
             </div>
         </gs-app>`;
     },
     args: {
         lapisField: 'host',
         placeholderText: 'Enter host name',
+        initialValue: 'Homo sapiens',
     },
 };
 
-export const FiresEvent: StoryObj<{ lapisField: string; placeholderText: string }> = {
+export const FiresEvent: StoryObj<TextInputProps> = {
     ...Default,
     play: async ({ canvasElement, step }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-text-input');
@@ -89,4 +105,8 @@ export const FiresEvent: StoryObj<{ lapisField: string; placeholderText: string
             );
         });
     },
+    args: {
+        ...Default.args,
+        initialValue: '',
+    },
 };

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

@@ -4,18 +4,49 @@ import { TextInput } from '../../preact/textInput/text-input';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed - When the text input has changed
+ *
+ * ## Context
+ *
+ * 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.
+ * The `details` of this event contain an object with the `lapisField` as key and the input value as value.
+ * Example:
+ * ```
+ * {
+ *  "host": "Homo sapiens"
+ * }
+ *  ```
  */
 @customElement('gs-text-input')
 export class TextInputComponent extends PreactLitAdapter {
+    /**
+     * The initial value to use for this text input.
+     */
+    @property()
+    initialValue: string | undefined = '';
+
+    /**
+     * The Lapis field name to use for this text input.
+     */
     @property()
     lapisField = '';
 
+    /**
+     * The placeholder text to display in the input field.
+     */
     @property()
-    placeholderText = '';
+    placeholderText: string | undefined = '';
 
     override render() {
-        return <TextInput lapisField={this.lapisField} placeholderText={this.placeholderText} />;
+        return (
+            <TextInput
+                lapisField={this.lapisField}
+                placeholderText={this.placeholderText}
+                initialValue={this.initialValue}
+            />
+        );
     }
 }
 

package/src/web-components/display/aggregate-component.mdx

@@ -1,25 +0,0 @@
-import { ArgTypes, Description, Meta, Story, Title, Source } from '@storybook/blocks';
-
-import * as AggregateComponentStories from './aggregate-component.stories.ts';
-
-<Meta of={AggregateComponentStories} name='Docs' />
-
-<Title of={AggregateComponentStories} />
-
-<Description of={AggregateComponentStories} />
-
-## Specification
-
-<ArgTypes of={AggregateComponentStories} />
-
-## Example
-
-<Source
-    code={`<gs-aggregate-component fields="['division', 'host']" filter='{"country": "USA"}'></gs-aggregate-component>`}
-/>
-
-### Live Example
-
-[See here](?path=/story/visualization-aggregate--template)
-
-<Story of={AggregateComponentStories.Table} />

package/src/web-components/input/location-filter.mdx

@@ -1,25 +0,0 @@
-import { ArgTypes, Description, Meta, Story, Title, Source } from '@storybook/blocks';
-
-import * as LocationFilterStories from './location-filter-component.stories.ts';
-
-<Meta of={LocationFilterStories} name='Docs' />
-
-<Title of={LocationFilterStories} />
-
-<Description of={LocationFilterStories} />
-
-## Specification
-
-<ArgTypes of={LocationFilterStories} />
-
-## Example
-
-<Source
-    code={`<gs-location-filter fields="['continent', 'country']" value='Europe / Switzerland'></gs-location-filter>`}
-/>
-
-### Live Example
-
-[See here](?path=/story/input-location-filter--location-filter)
-
-<Story of={LocationFilterStories.LocationFilter} />