Add a slot to show search tips

src/langs/json/en.json

@@ -11,7 +11,10 @@
     "title": "Title"
   },
   "search": {
-    "matchingResults": "{n, plural, one {# matching result} other {# matching results}}"
+    "matchingResults": "{n, plural, one {# matching result} other {# matching results}}",
+    "reset": "Clear Search",
+    "help": "Use filters like <code>user:</code>, <code>project:</code> or <code>organization:</code> to refine searches. Use <code>sort:</code> to order results.",
+    "more": "Learn more"
   },
   "homeTemplate": {
     "signedIn": "Signed in as {name}",

src/lib/components/forms/Search.svelte

@@ -11,6 +11,7 @@
   export let query: string = "";
   export let placeholder: string = $_("common.search");
   export let action: Maybe<string> = undefined;
+  export let id = "query";
 
   let input: HTMLInputElement;
   let form: HTMLFormElement;
@@ -48,50 +49,46 @@
   on:reset={clear}
   bind:this={form}
 >
-  <label for="query" title="Search">
+  <label for={id} title={$_("common.search")}>
     <Search16 />
     <span class="sr-only">{$_("common.search")}</span>
+    <input
+      type="search"
+      {id}
+      autocomplete="off"
+      spellcheck="false"
+      {name}
+      {placeholder}
+      bind:value={query}
+      bind:this={input}
+      on:change
+      on:input
+    />
+    <button
+      title={$_("search.reset")}
+      type="reset"
+      class:hidden={!query}
+      on:click={clear}
+    >
+      <XCircleFill24 />
+    </button>
   </label>
-  <input
-    type="search"
-    id="query"
-    autocomplete="off"
-    {name}
-    {placeholder}
-    bind:value={query}
-    bind:this={input}
-    on:change
-    on:input
-  />
-  <button
-    title="Clear Search"
-    type="reset"
-    class:hidden={!query}
-    on:click={clear}
-  >
-    <XCircleFill24 />
-  </button>
+  {#if $$slots.help}<div class="help"><slot name="help" /></div>{/if}
 </form>
 
 <style>
   form {
     display: flex;
+    flex-direction: column;
     align-self: stretch;
+    align-items: baseline;
     gap: 0.25rem;
-    padding: 0 0.5rem;
+    margin: 0.25rem;
 
     color: var(--gray-5, #233944);
     fill: var(--gray-5, #233944);
-    border: 1px solid var(--gray-2);
-    border-radius: 0.5rem;
-
-    overflow: hidden;
-  }
-  form:focus-within {
-    outline: inherit;
-    border-color: var(--blue-3);
-    box-shadow: 0 0 0 1px var(--blue-3);
   }
+
   input {
     flex: 1 0 0;
     appearance: none;
@@ -103,21 +100,39 @@
     font-size: var(--font-md, 1rem);
     box-shadow: none;
   }
+
   input:focus {
     outline: none;
   }
+
   input::placeholder {
     color: var(--gray-4, #5c717c);
   }
+
   input[type="search"]::-webkit-search-cancel-button,
   input[type="search"]::-webkit-search-decoration {
     -webkit-appearance: none;
     appearance: none;
   }
+
   label {
     display: flex;
     align-items: center;
+    width: 100%;
+
+    border: 1px solid var(--gray-2);
+    border-radius: 0.5rem;
+    padding: 0 0.5rem;
+
+    overflow: hidden;
+  }
+
+  label:focus-within {
+    outline: inherit;
+    border-color: var(--blue-3);
+    box-shadow: 0 0 0 1px var(--blue-3);
   }
+
   button {
     flex: 0 0 0;
     appearance: none;
@@ -139,6 +154,7 @@
       opacity 0.125s linear,
       visibility 0s;
   }
+
   button.hidden {
     visibility: hidden;
     opacity: 0;
@@ -149,4 +165,10 @@
       visibility 0s linear 0.25s,
       position 0s linear 0.25s;
   }
+
+  .help {
+    flex: 1 1 100%;
+    font-size: var(--font-s);
+    color: var(--gray-4);
+  }
 </style>

src/lib/components/forms/stories/Search.stories.svelte

@@ -4,7 +4,7 @@
   import Search from "../Search.svelte";
 
   export const meta = {
-    title: "Components / Search",
+    title: "Forms / Search",
     component: Search,
     parameters: { layout: "centered" },
   };
@@ -25,3 +25,16 @@
 
 <Story name="With Query" {args} />
 <Story name="Without Query" args={{ query: "" }} />
+
+<Story name="With help">
+  <div style="width: 60ch">
+    <Search {...args} on:submit={submit} on:change={change}>
+      <span slot="help">
+        Search tips: add filters by typing <code>user:</code>,
+        <code>project:</code>, or <code>organization:</code>, etc. Use
+        <code>sort:</code> to order results.
+      </span>
+      <a href="https://www.documentcloud.org/help/search">Learn more</a>
+    </Search>
+  </div>
+</Story>

src/lib/components/layouts/DocumentBrowser.svelte

@@ -72,10 +72,10 @@
   export let query: string = "";
   export let project: Nullable<Project> = null;
   export let uiText: UITextProps = {
-    loading: $_("common.loading"),
-    error: $_("common.error"),
-    empty: $_("common.empty"),
-    search: $_("common.search"),
+    loading: "common.loading",
+    error: "common.error",
+    empty: "common.empty",
+    search: "common.search",
   };
 
   let width: number;
@@ -154,7 +154,14 @@
             <PageToolbar>
               <Flex slot="right">
                 <div style:flex="1 1 auto">
-                  <Search name="q" {query} placeholder={uiText.search} />
+                  <Search name="q" {query} placeholder={$_(uiText.search)}>
+                    <span slot="help">
+                      {@html $_("search.help")}
+                      <a target="_blank" href="/help/search/">
+                        {$_("search.more")}
+                      </a>
+                    </span>
+                  </Search>
                 </div>
               </Flex>
             </PageToolbar>
@@ -173,10 +180,10 @@
         {/if}
       </svelte:fragment>
       {#await searchResults}
-        <Empty icon={Hourglass24}>{uiText.loading}</Empty>
+        <Empty icon={Hourglass24}>{$_(uiText.loading)}</Empty>
       {:then documentsResults}
         {#if !query && !documentsResults.results?.length}
-          <Empty icon={FileDirectory24}>{uiText.empty}</Empty>
+          <Empty icon={FileDirectory24}>{$_(uiText.empty)}</Empty>
         {:else}
           <ResultsList
             results={documentsResults.results}
@@ -192,7 +199,7 @@
           </ResultsList>
         {/if}
       {:catch}
-        <Error>{uiText.error}</Error>
+        <Error>{$_(uiText.error)}</Error>
       {/await}
       <svelte:fragment slot="footer">
         {#if !embed}