Skip to content

Build your personal knowledge base with Trilium Notes

feat(quick_search): show the shortcut hints from the results' footer

Elian Doran01300e310d41
diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.json
index c9007bd698..6f8b0d1234 100644
--- a/apps/client/src/translations/en/translation.json
+++ b/apps/client/src/translations/en/translation.json
@@ -2756,7 +2756,13 @@
"searching": "Searching...",
"no-results": "No results found",
"more-results": "... and {{number}} more results.",
- "show-in-full-search": "Show in full search"
+ "show-in-full-search": "Show in full search",
+ "hints": {
+ "title": "Quick search results",
+ "to_results": "Move to the results",
+ "page": "Move a page through the results",
+ "close": "Close the results"
+ }
},
"note_tree": {
"collapse-title": "Collapse note tree",
diff --git a/apps/client/src/widgets/quick_search.css b/apps/client/src/widgets/quick_search.css
index a8f8fd4aa5..48e8175f6d 100644
--- a/apps/client/src/widgets/quick_search.css
+++ b/apps/client/src/widgets/quick_search.css
@@ -148,10 +148,14 @@
.quick-search-footer {
display: flex;
flex: 0 0 auto;
- justify-content: flex-end;
+ align-items: center;
padding: var(--menu-padding-size, .5rem);
border-top: 1px solid var(--dropdown-border-color, var(--main-border-color));
+ .show-in-full-search {
+ margin-inline-start: auto;
+ }
+
kbd {
padding: .1875rem .375rem;
}
diff --git a/apps/client/src/widgets/quick_search.spec.tsx b/apps/client/src/widgets/quick_search.spec.tsx
index 2f730ce206..981610d2ed 100644
--- a/apps/client/src/widgets/quick_search.spec.tsx
+++ b/apps/client/src/widgets/quick_search.spec.tsx
@@ -319,8 +319,8 @@ describe("QuickSearch", () => {
// Pinned below the scroller rather than at the end of the list, so it is always in reach.
const footer = menu()?.lastElementChild;
expect(footer?.classList.contains("quick-search-footer")).toBe(true);
- const button = footer?.querySelector<HTMLButtonElement>("button");
- if (!button) throw new Error("The footer has no button.");
+ const button = footer?.querySelector<HTMLButtonElement>(".show-in-full-search");
+ if (!button) throw new Error("The footer has no full search button.");
await act(async () => button.click());
expect(triggerCommand).toHaveBeenCalledWith("searchNotes", { searchString: "#book AND tolkien" });
@@ -337,6 +337,34 @@ describe("QuickSearch", () => {
expect(menu()).toBeNull();
});
+ it("opens the shortcut hints from the footer, and stays open for a press in them", async () => {
+ vi.spyOn(server, "get").mockResolvedValue(response(3, []));
+ const triggerEvent = vi.spyOn(appContext, "triggerEvent").mockResolvedValue(undefined);
+ const { editor } = await mount();
+
+ typeQuery(editor, "hello");
+ pressEnter(editor);
+ await waitForResults(3);
+
+ const button = menu()?.querySelector<HTMLButtonElement>(".quick-search-footer .shortcut-hint-button");
+ if (!button) throw new Error("The footer has no shortcut hints button.");
+ await act(async () => button.click());
+
+ const [ name, data ] = triggerEvent.mock.calls.find(([ event ]) => event === "shortcutHintsRequested") ?? [];
+ expect(name).toBe("shortcutHintsRequested");
+ const titles = (data as { sections: { titleKey?: string }[] }).sections.map((section) => section.titleKey);
+ expect(titles).toEqual(expect.arrayContaining([ "search_string.hints.title", "quick-search.hints.title" ]));
+
+ const pane = document.createElement("div");
+ pane.className = "shortcut-hints-panel";
+ document.body.append(pane);
+ act(() => {
+ pane.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+ });
+ expect(menu()).not.toBeNull();
+ pane.remove();
+ });
+
it("leaves the open results alone while the query is typed", async () => {
vi.spyOn(server, "get").mockResolvedValue(response(15, []));
const { editor } = await mount();
diff --git a/apps/client/src/widgets/quick_search.tsx b/apps/client/src/widgets/quick_search.tsx
index fc73e53299..47366429a1 100644
--- a/apps/client/src/widgets/quick_search.tsx
+++ b/apps/client/src/widgets/quick_search.tsx
@@ -10,15 +10,32 @@ import appContext from "../components/app_context";
import { t } from "../services/i18n";
import { calculateHash, type ViewScope } from "../services/link";
import server from "../services/server";
+import type { ShortcutHintDefinition } from "../services/shortcut_hints";
+import { isMobile } from "../services/utils";
import ActionButton from "./react/ActionButton";
import Button from "./react/Button";
import { focusListItem } from "./react/FormList";
import { useTriliumEvent } from "./react/hooks";
import Icon from "./react/Icon";
import { pointerMoved } from "./react/menu_context";
+import OverlayControlGroup from "./react/OverlayControlGroup";
import Popup from "./react/Popup";
import RawHtml, { RawHtmlBlock } from "./react/RawHtml";
import SearchStringEditor from "./ribbon/SearchStringEditor";
+import { ShortcutHintOverlayButton } from "./shortcut_hints/shortcut_hint_button";
+
+/** The keys the results answer, beside the field's own, for the shortcut-hints pane. */
+const QUICK_SEARCH_HINTS: ShortcutHintDefinition = [
+ {
+ titleKey: "quick-search.hints.title",
+ hints: [
+ { keys: [ "Down" ], labelKey: "quick-search.hints.to_results" },
+ { keys: [ "PageDown", "PageUp" ], labelKey: "quick-search.hints.page" },
+ { keys: [ "Ctrl+Enter" ], labelKey: "quick-search.show-in-full-search" },
+ { keys: [ "Escape" ], labelKey: "quick-search.hints.close" }
+ ]
+ }
+];
/** The keys that move focus through the results. */
const NAVIGATION_KEYS = new Set([ "ArrowDown", "ArrowUp", "PageDown", "PageUp" ]);
@@ -111,6 +128,7 @@ export default function QuickSearch() {
className="search-string"
placeholder={t("quick-search.placeholder")}
singleLine
+ extraShortcutHints={QUICK_SEARCH_HINTS}
editorRef={editorRef}
onChange={(value) => {
searchStringRef.current = value;
@@ -143,6 +161,7 @@ export default function QuickSearch() {
keyboardDriven && "tn-menu-keyboard")}
elementRef={popupRef}
escapeDismisses={false}
+ keepOpenSelector=".shortcut-hints-panel"
onPointerMove={(e) => {
if (!pointerMoved(e)) return;
setKeyboardDriven(false);
@@ -160,7 +179,13 @@ export default function QuickSearch() {
<QuickSearchResults searchState={searchState} onOpenResult={close} />
</div>
<div className="quick-search-footer">
+ {!isMobile() && (
+ <OverlayControlGroup>
+ <ShortcutHintOverlayButton />
+ </OverlayControlGroup>
+ )}
<Button
+ className="show-in-full-search"
text={t("quick-search.show-in-full-search")}
keyboardShortcut="Ctrl+Enter"
size="small"
diff --git a/apps/client/src/widgets/react/Popup.css b/apps/client/src/widgets/react/Popup.css
index 8145b6f35b..31264cb583 100644
--- a/apps/client/src/widgets/react/Popup.css
+++ b/apps/client/src/widgets/react/Popup.css
@@ -7,8 +7,8 @@ body .tn-popup {
top: 0;
left: 0;
/* As a portaled dropdown menu: over a modal (1055) and a stacked quick-edit popup (1100), under
- a search field's completions (1210, search_field_editor.css) and the prompts (2000) it can
- summon. */
+ a search field's completions and the shortcut-hints pane (1210, search_field_editor.css,
+ shortcut_hints_panel.css) and the prompts (2000) it can summon. */
z-index: 1200;
visibility: hidden;
}
diff --git a/apps/client/src/widgets/react/Popup.spec.tsx b/apps/client/src/widgets/react/Popup.spec.tsx
index 091e485742..35c1f0f8ae 100644
--- a/apps/client/src/widgets/react/Popup.spec.tsx
+++ b/apps/client/src/widgets/react/Popup.spec.tsx
@@ -159,6 +159,23 @@ describe("Popup", () => {
fullscreen.remove();
});
+ it("stays open for a press in what `keepOpenSelector` names, elsewhere in the page", async () => {
+ anchorAt(100, 50);
+ const onDismiss = vi.fn();
+ await open({ onDismiss, keepOpenSelector: ".hints-pane" });
+ const pane = document.createElement("div");
+ pane.className = "hints-pane";
+ pane.innerHTML = "<span>Ctrl+Space</span>";
+ document.body.append(pane);
+
+ pane.firstElementChild?.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+ expect(onDismiss).not.toHaveBeenCalled();
+
+ document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+ expect(onDismiss).toHaveBeenCalledWith("outside");
+ pane.remove();
+ });
+
it("is dismissed by a press outside it and its anchor, and by Escape, which goes no further", async () => {
anchorAt(100, 50);
const onDismiss = vi.fn();
diff --git a/apps/client/src/widgets/react/Popup.tsx b/apps/client/src/widgets/react/Popup.tsx
index b46e356a72..2e084b9284 100644
--- a/apps/client/src/widgets/react/Popup.tsx
+++ b/apps/client/src/widgets/react/Popup.tsx
@@ -55,13 +55,18 @@ export interface PopupProps extends Pick<HTMLAttributes<HTMLDivElement>, "id" |
onDismiss?(reason: "outside" | "escape"): void;
/** Whether Escape dismisses it, as it does unless its content answers Escape itself, as a menu does. */
escapeDismisses?: boolean;
+ /**
+ * A press in an element this selector matches does not dismiss it, for a surface it summons that
+ * renders elsewhere in the page, as the shortcut-hints pane does. Named as on `Popover`.
+ */
+ keepOpenSelector?: string;
children?: ComponentChildren;
}
/** How many pixels it keeps from the edges of the viewport. */
const VIEWPORT_PADDING = 5;
-export default function Popup({ anchor, placement = "bottom-start", offset: gap = 0, capHeight = true, portalClassName, placedByStylesheet, backdropClassName, elementRef, container, onPlaced, onDismiss, escapeDismisses = true, className, children, ...elementProps }: PopupProps) {
+export default function Popup({ anchor, placement = "bottom-start", offset: gap = 0, capHeight = true, portalClassName, placedByStylesheet, backdropClassName, elementRef, container, onPlaced, onDismiss, escapeDismisses = true, keepOpenSelector, className, children, ...elementProps }: PopupProps) {
const popupRef = useRef<HTMLDivElement | null>(null);
// Stable, so the element is handed on once rather than taken back and given again each render.
const setElement = useCallback((element: HTMLDivElement | null) => {
@@ -128,6 +133,8 @@ export default function Popup({ anchor, placement = "bottom-start", offset: gap
dismiss.current = onDismiss;
const escapes = useRef(escapeDismisses);
escapes.current = escapeDismisses;
+ const keepOpen = useRef(keepOpenSelector);
+ keepOpen.current = keepOpenSelector;
useLayoutEffect(() => {
if (!dismiss.current) return;
// Captured at the window, so a host that stops its own presses, as the note tree does,
@@ -137,6 +144,7 @@ export default function Popup({ anchor, placement = "bottom-start", offset: gap
const target = e.target as Node;
if (layer.contains(target)) return;
if (anchor instanceof HTMLElement && anchor.contains(target)) return;
+ if (keepOpen.current && target instanceof Element && target.closest(keepOpen.current)) return;
dismiss.current?.("outside");
swallowStrayClick(target);
};
diff --git a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
index 90173fc54c..8d88772184 100644
--- a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
+++ b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
@@ -23,6 +23,11 @@ interface SearchStringEditorProps {
autoFocus?: boolean;
/** Whether the query is held to one line, for a field laid out as an input. */
singleLine?: boolean;
+ /**
+ * Shortcut-hint sections listed after the field's own, for a caller whose keys go beyond the
+ * field's. A host takes one set of hints, so the caller hands them here rather than registering.
+ */
+ extraShortcutHints?: ShortcutHintDefinition;
/** Handed the editor once built, for a caller that has to focus or select what it holds. */
editorRef?: MutableRef<FieldEditor | undefined>;
onChange(newValue: string): void;
@@ -71,7 +76,7 @@ const SINGLE_LINE_HINTS: ShortcutHintDefinition = [
*
* Written to edit the `#searchString` of a saved search, and used for a collection filter too.
*/
-export default function SearchStringEditor({ currentValue, noteId, placeholder, ariaLabel, className, autoFocus, singleLine, editorRef: exposedRef, onChange, onEnter, onArrowDown, onEscape }: SearchStringEditorProps) {
+export default function SearchStringEditor({ currentValue, noteId, placeholder, ariaLabel, className, autoFocus, singleLine, extraShortcutHints, editorRef: exposedRef, onChange, onEnter, onArrowDown, onEscape }: SearchStringEditorProps) {
const parentRef = useRef<HTMLDivElement>(null);
const editorRef = useRef<FieldEditor>();
// The editor is built once, so it reaches the current props through a ref rather than
@@ -82,7 +87,10 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
// report it as an edit the user made.
const isAdopting = useRef(false);
- useContextualShortcutHints(singleLine ? SINGLE_LINE_HINTS : SEARCH_STRING_HINTS);
+ useContextualShortcutHints(() => [
+ ...(singleLine ? SINGLE_LINE_HINTS : SEARCH_STRING_HINTS),
+ ...(extraShortcutHints ?? [])
+ ]);
useEffect(() => {
if (!parentRef.current) {
diff --git a/apps/client/src/widgets/shortcut_hints/shortcut_hints_panel.css b/apps/client/src/widgets/shortcut_hints/shortcut_hints_panel.css
index d22885a77e..fa2c8aceb0 100644
--- a/apps/client/src/widgets/shortcut_hints/shortcut_hints_panel.css
+++ b/apps/client/src/widgets/shortcut_hints/shortcut_hints_panel.css
@@ -2,7 +2,8 @@
position: fixed;
right: 1rem;
bottom: 1rem;
- z-index: 1080;
+ /* Over a `Popup` (1200, Popup.css), from which its button can open it. */
+ z-index: 1210;
/* Grow to fit the widest shortcut row (so keys never wrap), capped to the viewport. */
width: max-content;
max-width: min(90vw, 640px);
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.html
index f4cfbfce3f..a36c1d5217 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.html
@@ -80,6 +80,9 @@
<li>Press <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to open the query in the full search.</li>
<li>Press <kbd>Escape</kbd> to close the results.</li>
</ul>
+<p>To see these shortcuts on screen, click the <kbd>?</kbd> button below the
+ results, or press <kbd>Alt</kbd>+<kbd>F1</kbd> while the search field is
+ focused.</p>
<h2>Using Quick Search</h2>
<ol>
<li><strong>Typo tolerance</strong>: Search finds results despite minor typos</li>
diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.md b/docs/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.md
index 81b449f327..550b4cbcb8 100644
--- a/docs/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.md
+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Navigation/Quick search.md
@@ -63,6 +63,8 @@ To search the whole database while hoisted, use the full <a class="reference-li
* Press <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to open the query in the full search.
* Press <kbd>Escape</kbd> to close the results.
+To see these shortcuts on screen, click the <kbd>?</kbd> button below the results, or press <kbd>Alt</kbd>+<kbd>F1</kbd> while the search field is focused.
+
## Using Quick Search
1. **Typo tolerance**: Search finds results despite minor typos