Feature: global search, keyboard shortcuts / hotkey support (paperles…

…s-ngx#6449)

docs/api.md

@@ -11,7 +11,7 @@ The API provides the following main endpoints:
 - `/api/correspondents/`: Full CRUD support.
 - `/api/custom_fields/`: Full CRUD support.
 - `/api/documents/`: Full CRUD support, except POSTing new documents.
- See below.
+ See [below](#posting-documents-file-uploads).
 - `/api/document_types/`: Full CRUD support.
 - `/api/groups/`: Full CRUD support.
 - `/api/logs/`: Read-Only.
@@ -24,6 +24,7 @@ The API provides the following main endpoints:
 - `/api/tasks/`: Read-only.
 - `/api/users/`: Full CRUD support.
 - `/api/workflows/`: Full CRUD support.
+- `/api/search/` GET, see [below](#global-search).
 
 All of these endpoints except for the logging endpoint allow you to
 fetch (and edit and delete where appropriate) individual objects by
@@ -188,6 +189,38 @@ The REST api provides four different forms of authentication.
  [configuration](configuration.md#PAPERLESS_ENABLE_HTTP_REMOTE_USER_API)),
  you can authenticate against the API using Remote User auth.
 
+## Global search
+
+A global search endpoint is available at `/api/search/` and requires a search term
+of > 2 characters e.g. `?query=foo`. This endpoint returns a maximum of 3 results
+across nearly all objects, e.g. documents, tags, saved views, mail rules, etc.
+Results are only included if the requesting user has the appropriate permissions.
+
+Results are returned in the following format:
+
+```json
+{
+ total: number
+ documents: []
+ saved_views: []
+ correspondents: []
+ document_types: []
+ storage_paths: []
+ tags: []
+ users: []
+ groups: []
+ mail_accounts: []
+ mail_rules: []
+ custom_fields: []
+ workflows: []
+}
+```
+
+Global search first searches objects by name (or title for documents) matching the query.
+If the optional `db_only` parameter is set, only document titles will be searched. Otherwise,
+if the amount of documents returned by a simple title string search is < 3, results from the
+search index will also be included.
+
 ## Searching for documents
 
 Full text searching is available on the `/api/documents/` endpoint. Two

docs/usage.md

@@ -550,6 +550,16 @@ collection.
 
 ## Searching {#basic-usage_searching}
 
+### Global search
+
+The top search bar in the web UI performs a "global" search of the various
+objects Paperless-ngx uses, including documents, tags, workflows, etc. Only
+objects for which the user has appropriate permissions are returned. For
+documents, if there are < 3 results, "advanced" search results (which use
+the document index) will also be included. This can be disabled under settings.
+
+### Document searches
+
 Paperless offers an extensive searching mechanism that is designed to
 allow you to quickly find a document you're looking for (for example,
 that thing that just broke and you bought a couple months ago, that
@@ -605,6 +615,12 @@ language](https://whoosh.readthedocs.io/en/latest/querylang.html). For
 details on what date parsing utilities are available, see [Date
 parsing](https://whoosh.readthedocs.io/en/latest/dates.html#parsing-date-queries).
 
+## Keyboard shortcuts / hotkeys
+
+A list of available hotkeys can be shown on any page using <kbd>Shift</kbd> +
+<kbd>?</kbd>. The help dialog shows only the keys that are currently available
+based on which area of Paperless-ngx you are using.
+
 ## The recommended workflow {#usage-recommended-workflow}
 
 Once you have familiarized yourself with paperless and are ready to use

src-ui/e2e/document-list/document-list.spec.ts

@@ -45,8 +45,8 @@ test('basic filtering', async ({ page }) => {
 test('text filtering', async ({ page }) => {
  await page.routeFromHAR(REQUESTS_HAR2, { notFound: 'fallback' })
  await page.goto('/documents')
- await page.getByRole('textbox').click()
- await page.getByRole('textbox').fill('test')
+ await page.getByRole('main').getByRole('combobox').click()
+ await page.getByRole('main').getByRole('combobox').fill('test')
  await expect(page.locator('pngx-document-list')).toHaveText(/32 documents/)
  await expect(page).toHaveURL(/title_content=test/)
  await page.getByRole('button', { name: 'Title & content' }).click()
@@ -59,12 +59,12 @@ test('text filtering', async ({ page }) => {
  await expect(page.locator('pngx-document-list')).toHaveText(/26 documents/)
  await page.getByRole('button', { name: 'Advanced search' }).click()
  await page.getByRole('button', { name: 'ASN' }).click()
- await page.getByRole('textbox').fill('1123')
+ await page.getByRole('main').getByRole('combobox').nth(1).fill('1123')
  await expect(page).toHaveURL(/archive_serial_number=1123/)
  await expect(page.locator('pngx-document-list')).toHaveText(/one document/i)
  await page.locator('select').selectOption('greater')
- await page.getByRole('textbox').click()
- await page.getByRole('textbox').fill('1123')
+ await page.getByRole('main').getByRole('combobox').nth(1).click()
+ await page.getByRole('main').getByRole('combobox').nth(1).fill('1123')
  await expect(page).toHaveURL(/archive_serial_number__gt=1123/)
  await expect(page.locator('pngx-document-list')).toHaveText(/5 documents/)
  await page.locator('select').selectOption('less')