From 29a54cccd161c01c61abd9390bd7c75c8ef72b22 Mon Sep 17 00:00:00 2001
From: "Jonas Kellerer (TNG)" <jonas.kellerer@tngtech.com>
Date: Tue, 14 May 2024 09:29:48 +0200
Subject: [PATCH] docs(components): documents mutation filter component #201

---
 .../mutation-filter-component.stories.ts      | 16 ++++--
 .../input/mutation-filter-component.tsx       | 52 ++++++++++++++++++-
 2 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/components/src/web-components/input/mutation-filter-component.stories.ts b/components/src/web-components/input/mutation-filter-component.stories.ts
index 14ce6f48..c57590f8 100644
--- a/components/src/web-components/input/mutation-filter-component.stories.ts
+++ b/components/src/web-components/input/mutation-filter-component.stories.ts
@@ -3,22 +3,32 @@ 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;
diff --git a/components/src/web-components/input/mutation-filter-component.tsx b/components/src/web-components/input/mutation-filter-component.tsx
index 49c8b920..95604ea9 100644
--- a/components/src/web-components/input/mutation-filter-component.tsx
+++ b/components/src/web-components/input/mutation-filter-component.tsx
@@ -6,11 +6,59 @@ import { MutationFilter, type SelectedMutationFilterStrings } from '../../preact
 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;