Merge pull request #2186 from thseiler/feature/autocomplete-for-fields

UI: generalize autocompletion to work for single-choice fields

Author: stanislaw

docs/strictdoc_01_user_guide.sdoc

@@ -1519,7 +1519,7 @@ The supported field types are:
    :widths: 20 80
    :header-rows: 1
 
-   * - **Field Type**
+   * - **Field type**
      - **Description**
 
    * - ``String``
@@ -1539,6 +1539,10 @@ The supported field types are:
    * - ``Reference``
      - **DEPRECATED:** comma-separated list with allowed reference types: ``ParentReqReference``, ``FileReference``. In the newer versions of StrictDoc (0.0.45+), a separate ``RELATIONS:`` section is used to configure the available relations.
 
+.. note::
+
+    The **field type** also influences how the field is presented in the web editor UI. A ``SingleChoice`` field enables an auto-completion function, which is useful in cases where the same values are entered repeatedly (such as requirement owners, test case types, or status fields).
+
 Example:
 
 .. code-block:: text

strictdoc/backend/sdoc/models/document.py

@@ -6,7 +6,10 @@
 
 from strictdoc.backend.sdoc.document_reference import DocumentReference
 from strictdoc.backend.sdoc.models.document_config import DocumentConfig
-from strictdoc.backend.sdoc.models.document_grammar import DocumentGrammar
+from strictdoc.backend.sdoc.models.document_grammar import (
+    DocumentGrammar,
+    GrammarElement,
+)
 from strictdoc.backend.sdoc.models.document_view import DocumentView
 from strictdoc.backend.sdoc.models.model import (
     SDocDocumentContentIF,
@@ -15,8 +18,12 @@
     SDocNodeIF,
     SDocSectionIF,
 )
+from strictdoc.backend.sdoc.models.type_system import (
+    GrammarElementFieldSingleChoice,
+)
 from strictdoc.core.document_meta import DocumentMeta
 from strictdoc.helpers.auto_described import auto_described
+from strictdoc.helpers.cast import assert_cast
 from strictdoc.helpers.mid import MID
 
 
@@ -193,3 +200,21 @@ def enumerate_custom_content_field_titles(
         yield from self.grammar.elements[
             0
         ].enumerate_custom_content_field_titles()
+
+    def get_options_for_singlechoice(
+        self, element_type: str, field_name: str
+    ) -> List[str]:
+        """
+        Returns the list of valid options for a SingleChoice field in this document.
+        """
+        assert self.grammar is not None
+        grammar: DocumentGrammar = self.grammar
+        element: GrammarElement = grammar.elements_by_type[element_type]
+
+        field = element.fields_map[field_name]
+
+        choice_grammar_element_field: GrammarElementFieldSingleChoice = (
+            assert_cast(field, GrammarElementFieldSingleChoice)
+        )
+
+        return choice_grammar_element_field.options

strictdoc/export/html/_static/controllers/autocompletable_field_controller.js

@@ -26,6 +26,7 @@
       this.autocompletable = autocompletable
       this.hidden = autocompletable.nextElementSibling
       this.results = this.hidden.nextElementSibling
+      this.abortController = null;
 
       this.close()
 
@@ -46,6 +47,19 @@
         this.close()
       });
 
+      autocompletable.addEventListener("click", (event) => {      
+        /* Toggle between showing / hiding results. */
+        if (this.resultsShown) {
+          this.hideAndRemoveOptions();
+        } else {
+          /* If minLengthValue is 0, we want to get all possible options (i.e. for SingleChoice).
+             Otherwise, we want narrow-down-as-you-type behavior, and filter on remainig options.
+           */
+          const query = this.minLengthValue == 0 ? "" : this.autocompletable.innerText.trim();
+          this.fetchResults(query);
+        }
+      });
+
       autocompletable.addEventListener("input", (event) => {
         const query = autocompletable.innerText.trim()
         if (query && query.length >= this.minLengthValue) {
@@ -78,7 +92,6 @@
     }
 
     sibling(next) {
-      console.group(this.options)
       const options = this.options
       const selected = this.selectedOption
       const index = options.indexOf(selected)
@@ -100,6 +113,18 @@
       target.scrollIntoView({ behavior: "auto", block: "nearest" })
     }
 
+    selectText(text) {
+      const normalizedText = text.trim().toLowerCase();
+      const match = this.options.find(option => {
+        const label = option.getAttribute("data-autocompletable-label") || option.textContent;
+        return label.trim().toLowerCase() === normalizedText;
+      });
+    
+      if (match) {
+        this.select(match);
+      }
+    }
+
     onEscapeKeydown = (event) => {
       if (!this.resultsShown) return
 
@@ -109,20 +134,28 @@
     }
 
     onArrowDownKeydown = (event) => {
+      if (!this.resultsShown) return
+
       const item = this.sibling(true)
       if (item) this.select(item)
       event.preventDefault()
     }
 
     onArrowUpKeydown = (event) => {
+      if (!this.resultsShown) return
+
       const item = this.sibling(false)
       if (item) this.select(item)
       event.preventDefault()
     }
 
     onTabKeydown = (event) => {
-      const selected = this.selectedOption
-      if (selected) this.commit(selected)
+      if (!this.resultsShown) return
+
+      /* Either use the selected options, or else select the first result. */
+      const selected = this.selectedOption || this.sibling(true)
+      this.commit(selected)
+      event.preventDefault();
     }
 
     onEnterKeydown = (event) => {
@@ -194,14 +227,26 @@
     fetchResults = async (query) => {
       if (!this.hasUrlValue) return
 
+      /* Abort the previous request as we are about to send a new one. */
+      if (this.abortController) {
+        this.abortController.abort();
+      }
+      this.abortController = new AbortController();
+      const signal = this.abortController.signal;
+
       const url = this.buildURL(query)
       try {
         this.element.dispatchEvent(new CustomEvent("loadstart"))
-        const html = await this.doFetch(url)
+        const html = await this.doFetch(url, signal)
         this.replaceResults(html)
+        /* Check if an entry matches the current text and select it. */
+        this.selectText(this.autocompletable.innerText.trim());
         this.element.dispatchEvent(new CustomEvent("load"))
         this.element.dispatchEvent(new CustomEvent("loadend"))
       } catch (error) {
+        if (error.name === 'AbortError') {
+          return;
+        }
         this.element.dispatchEvent(new CustomEvent("error"))
         this.element.dispatchEvent(new CustomEvent("loadend"))
         throw error
@@ -217,8 +262,8 @@
       return url.toString()
     }
 
-    doFetch = async (url) => {
-      const response = await fetch(url)
+    doFetch = async (url, signal) => {
+      const response = await fetch(url, {signal})
 
       if (!response.ok) {
         throw new Error(`Server responded with status ${response.status}`)
@@ -301,3 +346,4 @@
   }
 
 })();
+

strictdoc/export/html/_static/form.css

@@ -165,7 +165,6 @@ sdoc-form-row-main {
   display: flex;
   flex-direction: column;
   position: relative;
-  z-index: 2;
 }
 
 sdoc-form-row-aside {
@@ -322,15 +321,12 @@ sdoc-autocompletable[contenteditable="false"] {
 
 .autocomplete-items {
   position: absolute;
-  border: 1px solid #d4d4d4;
+  border: 1px solid var(--color-action);
   background-color: var(--color-bg-contrast);
-  border-bottom: none;
-  border-top: none;
-  z-index: 99;
   top: 100%;
   left: 0;
   right: 0;
-  width: 40vw;
+  width: 33vw;
   max-height: 60vh;
   overflow-y: auto;
   z-index: 999;
@@ -433,7 +429,8 @@ sdoc-form-field select::-ms-expand {
   color: rgba(242, 100, 42,.2);
 }
 
-sdoc-contenteditable[data-field-suffix]:not(:empty)::after {
+sdoc-contenteditable[data-field-suffix]:not(:empty)::after,
+sdoc-autocompletable[data-field-suffix]:not(:empty)::after {
   content: attr(data-field-suffix);
   color: var(--color-fg-accent);
   margin-left: 4px;
@@ -563,8 +560,10 @@ sdoc-form-error + sdoc-form-field-group {
 
 sdoc-form-field-group[errors]::before, /* Grammar -> label for group of fields */
 sdoc-contenteditable[errors]::before, /* inside contenteditable errors block does not affected */
+sdoc-autocompletable[errors]::before,
 sdoc-form-error + sdoc-form-field > label, /* Grammar -> relation field ; File filed */
-sdoc-form-error + sdoc-form-field > sdoc-contenteditable::before {
+sdoc-form-error + sdoc-form-field > sdoc-contenteditable::before,
+sdoc-form-error + sdoc-form-field > sdoc-autocompletable::before {
   color: var(--color-danger);
 }
 

strictdoc/export/html/form_objects/requirement_form_object.py

@@ -58,19 +58,24 @@ def __init__(
         field_name: str,
         field_type: RequirementFormFieldType,
         field_value: str,
+        field_is_autocompletable: bool = False,
     ):
         assert isinstance(field_value, str)
         self.field_mid: str = field_mid
         self.field_name: str = field_name
         self.field_value: str = field_value
         self.field_type = field_type
+        self.field_is_autocompletable = field_is_autocompletable
 
-    def is_singleline(self):
+    def is_singleline(self) -> bool:
         return self.field_type == RequirementFormFieldType.SINGLELINE
 
-    def is_multiline(self):
+    def is_multiline(self) -> bool:
         return self.field_type == RequirementFormFieldType.MULTILINE
 
+    def is_autocompletable(self) -> bool:
+        return self.field_is_autocompletable
+
     def get_input_field_name(self):
         return f"requirement[fields][{self.field_mid}][value]"
 
@@ -104,6 +109,9 @@ def create_from_grammar_field(
                     else RequirementFormFieldType.SINGLELINE
                 ),
                 field_value=value,
+                field_is_autocompletable=(
+                    grammar_field.gef_type == RequirementFieldType.SINGLE_CHOICE
+                ),
             )
         raise NotImplementedError(grammar_field)
 
@@ -129,6 +137,9 @@ def create_existing_from_grammar_field(
                     else RequirementFormFieldType.SINGLELINE
                 ),
                 field_value=field_value,
+                field_is_autocompletable=(
+                    grammar_field.gef_type == RequirementFieldType.SINGLE_CHOICE
+                ),
             )
         raise NotImplementedError(grammar_field)
 

strictdoc/export/html/templates/autocomplete/field/stream_autocomplete_field.jinja.html

@@ -0,0 +1,2 @@
+{% for value in values %}
+<li class="autocompletable-result-item" role="option" data-autocompletable-value="{{ value }}">{{ value }}</li>{% endfor %}

strictdoc/export/html/templates/components/form/field/autocompletable/index.jinja

@@ -9,8 +9,9 @@
 {%- assert field_placeholder is not none, "field_placeholder is not none" -%}
 {%- assert field_value is defined, "field_value is defined" -%}
 {%- assert mid is defined, "mid is defined" -%}
-{%- assert requirement_mid is defined, "requirement_mid is defined" -%}
 {%- assert testid_postfix is defined, "testid_postfix is defined" -%}
+{%- assert autocomplete_url is defined, "autocomplete_url is defined" -%}
+{%- assert autocomplete_len is defined, "autocomplete_len is defined" -%}
 
 {% if field_required is not defined -%}
 {% set field_required=false -%}
@@ -50,7 +51,8 @@
     {%- endif -%}
     data-testid="form-field-{{ testid_postfix }}"
     data-autocompletable-target="input"
-    data-autocompletable-url-value="/autocomplete/uid?exclude_requirement_mid={{ requirement_mid }}"
+    data-autocompletable-url-value="{{ autocomplete_url }}"
+    data-autocompletable-min-length-value="{{ autocomplete_len }}"
   >
     {{- field_value -}}
   </sdoc-autocompletable>

strictdoc/export/html/templates/components/form/row/row_with_relation.jinja

@@ -1,5 +1,4 @@
 {% assert relation_row_context is defined, "row_with_relation: relation_row_context must be defined." %}
-
 {% assert relation_row_context.errors is defined, "row_with_relation: errors must be defined." %}
 {% assert relation_row_context.field is defined, "row_with_relation: field must be defined." %}
 {% assert relation_row_context.relation_types is defined, "row_with_relation: relation_types must be defined." %}
@@ -56,6 +55,8 @@
     field_type = "singleline",
     field_value = relation_row_context.field.field_value,
     mid = relation_row_context.field.field_mid,
+    autocomplete_url = "/autocomplete/uid?exclude_requirement_mid="~requirement_mid,
+    autocomplete_len = "2",
     testid_postfix = "relation-uid"
   %}
   {%- include "components/form/field/autocompletable/index.jinja" %}

strictdoc/export/html/templates/components/form/row/row_with_text_field.jinja

@@ -1,7 +1,6 @@
 {%- extends "components/form/row/index.jinja" %}
 
 {% assert text_field_row_context is defined, "row_with_text: row_context must be defined." %}
-
 {% assert text_field_row_context.errors is defined, "row_with_text: errors must be defined." %}
 {% assert text_field_row_context.field is defined, "row_with_text: field must be defined." %}
 {% assert text_field_row_context.field_type is defined, "row_with_text: field_type must be defined." %}
@@ -42,7 +41,19 @@
     field_value = text_field_row_context.field.field_value,
     testid_postfix = text_field_row_context.field.field_name
   %}
-  {%- include "components/form/field/contenteditable/index.jinja" %}
+    {%- if text_field_row_context.field.is_autocompletable() -%}
+      {#- Setting autocomplete_len to "0" will cause the sdoc-autocompletable
+          to act like a drop-down, (i.e. show all options on click) -#}
+      {%- with
+        autocomplete_url = "/autocomplete/field?document_mid="~document_mid~"&element_type="~element_type~"&field_name="~field_label,
+        result_class_name = "requirement__link",
+        autocomplete_len = "0"
+      %}
+        {%- include "components/form/field/autocompletable/index.jinja" %}
+      {%- endwith -%}
+    {%- else -%}
+      {%- include "components/form/field/contenteditable/index.jinja" %}
+    {%- endif -%}
   {%- endwith -%}
 
   <input

strictdoc/export/html/templates/screens/document/document/frame_requirement_form.jinja

@@ -25,6 +25,9 @@
 {# Fields #}
 <sdoc-tab-content id="Fields" active>
   {% set text_field_row_context = namespace() %}
+  {% set requirement_mid = form_object.requirement_mid %}
+  {% set document_mid = form_object.document_mid %}
+  {% set element_type = form_object.element_type %}
 
   {# Single-line #}
   {%- for field_values_ in form_object.enumerate_fields(multiline=False) -%}
@@ -68,7 +71,6 @@
     {% set relation_row_context.errors = field_.validation_messages %}
     {% set relation_row_context.relation_types = form_object.relation_types %}
     {% set relation_row_context.form_object = form_object %}
-    {% set requirement_mid = form_object.requirement_mid %}
     {% include "components/form/row/row_with_relation.jinja" %}
   {%- endfor -%}