From bfc01fbfd8e327fdee18268921e7725a44741514 Mon Sep 17 00:00:00 2001
From: Adrian Rudnik <adrian@klonmaschine.de>
Date: Tue, 31 Oct 2023 23:34:21 +0100
Subject: [PATCH] Added search examples

---
 frontend/src/components/parts/QueryInput.vue  |  38 +++-
 .../parts/search/SearchExamples.vue           | 165 ++++++++++++++++++
 frontend/src/locales/en.yaml                  |  67 ++++++-
 3 files changed, 260 insertions(+), 10 deletions(-)
 create mode 100644 frontend/src/components/parts/search/SearchExamples.vue

diff --git a/frontend/src/components/parts/QueryInput.vue b/frontend/src/components/parts/QueryInput.vue
index 7ca8c29f..5f9912e8 100644
--- a/frontend/src/components/parts/QueryInput.vue
+++ b/frontend/src/components/parts/QueryInput.vue
@@ -9,7 +9,7 @@
         :suggestions="suggestions"
         :virtualScrollerOptions="{ itemSize: 50, scrollWidth: '100vw', scrollHeight: '300px' }"
         multiple
-        placeholder="Search for files by string or tag"
+        :placeholder="t('query-input-component.placeholder')"
         @complete="aComplete"
         @item-select="clearAfterSelect"
         @clear="clearInput"
@@ -36,20 +36,38 @@
       </AutoComplete>
     </div>
 
-    <div class="Options flex justify-content-between gap-2 mt-2">
+    <div class="Options flex justify-content-between gap-2 mt-2 mb-3">
       <div class="my-2 text flex gap-2">
         <span>{{ t('query-input-component.hits', { count: currentResultCount }) }}</span>
-        <span class="text-red-500" v-if="!currentRequestValid">INVALID QUERY</span>
+        <span class="text-red-500" v-if="!currentRequestValid">
+          {{ t('query-input-component.invalid-query') }}
+        </span>
       </div>
 
       <div class="flex justify-content-end gap-2">
-        <RouterLink v-slot="{ navigate }" to="/x" custom>
-          <Button @click="navigate" text size="small" label="examples" />
-        </RouterLink>
-
-        <Button @click="clearInput" text size="small" label="clear" />
+        <Button
+          @click="showHelp = !showHelp"
+          size="small"
+          :label="
+            !showHelp
+              ? t('query-input-component.action.show-examples')
+              : t('query-input-component.action.hide-examples')
+          "
+          :plain="!showHelp"
+          :text="!showHelp"
+        />
+
+        <Button
+          @click="clearInput"
+          plain
+          text
+          size="small"
+          :label="t('query-input-component.action.reset-search')"
+        />
       </div>
     </div>
+
+    <SearchExamples v-if="showHelp" />
   </div>
 </template>
 
@@ -66,7 +84,7 @@ import { useI18n } from 'vue-i18n'
 import { watchDebounced } from '@vueuse/core'
 import { executeQuerySearch } from '@/plugins/search'
 import Button from 'primevue/button'
-import { isEmpty } from 'lodash'
+import SearchExamples from '@/components/parts/search/SearchExamples.vue'
 
 const { t } = useI18n()
 const currentSelection = ref<Tag[]>([])
@@ -74,6 +92,8 @@ const suggestions = ref<Tag[]>([])
 const currentPlainValue = ref('')
 const hidePanel = ref(false)
 
+const showHelp = ref(false)
+
 const resultStore = useSearchResultStore()
 const statStore = useStatStore()
 
diff --git a/frontend/src/components/parts/search/SearchExamples.vue b/frontend/src/components/parts/search/SearchExamples.vue
new file mode 100644
index 00000000..4e5d40f9
--- /dev/null
+++ b/frontend/src/components/parts/search/SearchExamples.vue
@@ -0,0 +1,165 @@
+<template>
+  <TabView class="SearchExamples border-2">
+    <TabPanel :header="t('search-examples.basic.title')">
+      <p>
+        {{ t('search-examples.basic.rules.description') }}
+      </p>
+
+      <ul>
+        <li>
+          <i18n-t keypath="search-examples.basic.rules.list.1" tag="label">
+            <code>[tag] free text [tag]</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.rules.list.2.text" tag="label">
+            <template v-slot:e1>
+              <code>{{ t('search-examples.basic.rules.list.2.should') }}</code>
+            </template>
+
+            <template v-slot:e2>
+              <code>{{ t('search-examples.basic.rules.list.2.must') }}</code>
+            </template>
+          </i18n-t>
+        </li>
+
+        <li>
+          {{ t('search-examples.basic.rules.list.3') }}
+        </li>
+      </ul>
+
+      <p>
+        {{ t('search-examples.basic.rules.example.intro') }}
+      </p>
+
+      <i18n-t keypath="search-examples.basic.rules.example.explain.text" tag="p">
+        <template v-slot:e1>
+          <code>
+            [
+            {{ t('common.label.tag.s') }}
+            {{ t('common.label.beats-per-minute.nc', { count: 110 }) }}
+            ] [
+            {{ t('common.label.tag.s') }}
+            {{ t('common.label.beats-per-minute.nc', { count: 120 }) }}
+            ] Taste
+          </code>
+        </template>
+
+        <template v-slot:e2>
+          <code>
+            {{ t('common.label.beats-per-minute.nc', { count: 110 }) }}
+          </code>
+        </template>
+
+        <template v-slot:e3>
+          <code>
+            {{ t('common.label.beats-per-minute.nc', { count: 120 }) }}
+          </code>
+        </template>
+
+        <template v-slot:e4>
+          <code>Taste</code>
+        </template>
+
+        <template v-slot:e5>
+          <code>Taste of Marmalade</code>
+        </template>
+      </i18n-t>
+    </TabPanel>
+
+    <TabPanel :header="t('search-examples.basic.advanced.title')">
+      <p>
+        {{ t('search-examples.basic.advanced.examples.description') }}
+      </p>
+
+      <ul>
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.1" tag="label">
+            <code>+type:AudioTrack</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.2" tag="label">
+            <code>-type:MidiTrack</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.3" tag="label">
+            <code>type:MidiTrack +fx</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.4" tag="label">
+            <code>+bpm:>=110 +bpm:&lt;=120</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.5" tag="label">
+            <code>+filename: "Classic Disco-Flat vs Bumpy-118bpm.als"</code>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.6" tag="label">
+            <template v-slot:e1>
+              <code>-pathFolder:"/home/adrian/Downloads/ablegram/samples"</code>
+            </template>
+
+            <template v-slot:e2>
+              <code>pathAbsolute</code>
+            </template>
+          </i18n-t>
+        </li>
+
+        <li>
+          <i18n-t keypath="search-examples.basic.advanced.examples.list.7" tag="label">
+            <template v-slot:e1>
+              <code>MID</code>
+            </template>
+
+            <template v-slot:e2>
+              <code>MIDI</code>
+            </template>
+          </i18n-t>
+        </li>
+      </ul>
+    </TabPanel>
+  </TabView>
+</template>
+
+<script setup lang="ts">
+import TabView from 'primevue/tabview'
+import TabPanel from 'primevue/tabpanel'
+import { useI18n } from 'vue-i18n'
+
+const { t } = useI18n()
+</script>
+
+<style lang="scss">
+.SearchExamples {
+  .p-tabview-panels {
+    p,
+    li {
+      line-height: 1.8;
+    }
+
+    code {
+      white-space: nowrap;
+      font-size: 0.9em;
+      background-color: black;
+      color: white;
+      padding: 0.25rem;
+      border-radius: 0.25rem;
+    }
+
+    li {
+      padding-bottom: 6px;
+    }
+  }
+}
+</style>
diff --git a/frontend/src/locales/en.yaml b/frontend/src/locales/en.yaml
index 7337e6de..0134802a 100644
--- a/frontend/src/locales/en.yaml
+++ b/frontend/src/locales/en.yaml
@@ -168,6 +168,10 @@ common:
       s: Comment
       c: Comments | Comment | Comments
       nc: No comments | One comment | {count} comments
+    tag:
+      s: Tag
+      c: Tags | Tag | Tags
+      nc: No tags | One tag | {count} tags
 
 tags:
   sys: System
@@ -321,14 +325,75 @@ shutdown-confirm-modal:
   reject: Return
 
 query-input-component:
-  placeholder: Enter a search query
+  placeholder: Search by tag, string or boolean query
   hits: '@:common.label.search-result.nc'
+  invalid-query: Invalid query
+  action:
+    reset-search: clear
+    show-examples: examples / help
+    hide-examples: hide examples / help
 
 result-item-component:
   button:
     show-tags: '@:common.button.show-tags'
     hide-tags: '@:common.button.hide-tags'
 
+search-examples:
+  basic:
+    title: Basics
+    rules:
+      description: >-
+        The input field is a combination of automatic tag completion (via AutoComplete)
+        and manual input. Here are some rules of conduct:
+      list:
+        1: >-
+          If tags are to be used for the search, they must be entered first. The
+          combination {0} is not possible via the AutoComplete function.
+        2:
+          text: >-
+            The selection of several tags and possibly a free text is interpreted as a wish to
+            find everything, in the sense of {e1}, not {e2}. The selection of a single tag or word
+            is interpreted as a {e2}.
+          should: should # e1
+          must: must # e2
+        3: >-
+          The free texts are sorted by accuracy. The closer an entry is to the formulated text,
+          the higher the search result is displayed.
+      example:
+        intro: >-
+          Here is a simple example of a combined search and how the search engine understands it:
+        explain:
+          text: >-
+            {e1} searches all results that contain {e2}, {e3} or
+            the word {e4}. The more combinations found, the higher the search result. So the example
+            project {e5} with a {e2} could be the first result.
+
+    advanced:
+      title: Advanced
+      examples:
+        description: >-
+          Advanced search is possible via simple binary entries. Here are some examples to give ideas:
+        list:
+          1: >-
+            {0} searches only for audio tracks, regardless of whether additional
+            search parameters have been specified. Other types are also 'MidiTrack' and 'LiveSet'.
+          2: >-
+            {0} searches for all hits that are not MIDI tracks.
+          3: >-
+            {0} (watch the signs!) prefers MIDI tracks that must contain the word "fx".
+          4: >-
+            {0} searches for all data points that have the attribute BPM and whose
+            value lies between 110 and 120.
+          5: >-
+            {0} searches for all data points associated
+            with this exact filename.
+          6: >-
+            {e1} will exclude all results related to this folder. The same goes for the
+            absolute path of a file with {e2}.
+          7: >-
+            {e1} without any further information searches all manual info field entries for
+            the word {e1}, which includes e.g. the word {e2}.
+
 live-set-result-item-component:
   header: '@:common.label.live-set.s'