make it clearer where global events are

Author: shakyShane

special-pages/pages/history/app/components/App.jsx

@@ -4,20 +4,51 @@ import styles from './App.module.css';
 import { useEnv } from '../../../../shared/components/EnvironmentProvider.js';
 import { Header } from './Header.js';
 import { Results } from './Results.js';
-import { useRef } from 'preact/hooks';
+import { useEffect, useRef } from 'preact/hooks';
 import { Sidebar } from './Sidebar.js';
-import { useGlobalState } from '../global-state/GlobalStateProvider.js';
-import { useSelectionEvents, useSelected } from '../global-state/SelectionProvider.js';
-import { useGlobalHandlers } from '../global-state/HistoryServiceProvider.js';
+import { useData } from '../global-state/DataProvider.js';
+import { useResetSelectionsOnQueryChange, useRowInteractions, useSelected } from '../global-state/SelectionProvider.js';
+import {
+    useAuxClickHandler,
+    useButtonClickHandler,
+    useContextMenuForEntries,
+    useContextMenuForTitles,
+    useGlobalHandlers,
+    useLinkClickHandler,
+} from '../global-state/HistoryServiceProvider.js';
+import { useQueryEvents } from '../global-state/QueryProvider.js';
 
 export function App() {
     const { isDarkMode } = useEnv();
-    const containerRef = useRef(/** @type {HTMLElement|null} */ (null));
-    const { ranges, term, results } = useGlobalState();
+    const { ranges, results } = useData();
     const selected = useSelected();
 
+    /**
+     * The following handlers are application-global in nature, so I want them
+     * to be registered here for visibility
+     */
     useGlobalHandlers();
-    useSelectionEvents(containerRef);
+    useResetSelectionsOnQueryChange();
+    useQueryEvents();
+    useLinkClickHandler();
+    useButtonClickHandler();
+    useContextMenuForTitles();
+    useContextMenuForEntries();
+    useAuxClickHandler();
+
+    /**
+     * onClick can be passed directly to the main container,
+     * onKeyDown will be observed at the document level.
+     * todo: can this be resolved if the `main` element is given focus/tab-index?
+     */
+    const { onClick, onKeyDown } = useRowInteractions();
+
+    useEffect(() => {
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [onKeyDown]);
 
     return (
         <div class={styles.layout} data-theme={isDarkMode ? 'dark' : 'light'}>
@@ -27,7 +58,7 @@ export function App() {
             <header class={styles.header}>
                 <Header />
             </header>
-            <main class={cn(styles.main, styles.customScroller)} ref={containerRef} data-main-scroller data-term={term}>
+            <main class={cn(styles.main, styles.customScroller)} data-main-scroller onClick={onClick}>
                 <Results results={results} selected={selected} />
             </main>
         </div>

special-pages/pages/history/app/components/Header.js

@@ -5,9 +5,9 @@ import { SearchForm } from './SearchForm.js';
 import { Trash } from '../icons/Trash.js';
 import { useTypedTranslation } from '../types.js';
 import { useQueryContext } from '../global-state/QueryProvider.js';
-import { BTN_ACTION_DELETE_ALL } from '../constants.js';
-import { useGlobalState } from '../global-state/GlobalStateProvider.js';
+import { useData } from '../global-state/DataProvider.js';
 import { useSelected } from '../global-state/SelectionProvider.js';
+import { useHistoryServiceDispatch } from '../global-state/HistoryServiceProvider.js';
 
 /**
  */
@@ -34,17 +34,18 @@ export function Header() {
 function Controls({ term }) {
     const { t } = useTypedTranslation();
     const selected = useSelected();
+    const dispatch = useHistoryServiceDispatch();
     const buttonTxt = useComputed(() => {
         const hasTerm = term.value !== null && term.value.trim() !== '';
         const hasSelections = selected.value.size > 0;
         return hasTerm || hasSelections ? t('delete_some') : t('delete_all');
     });
-    const { results } = useGlobalState();
+    const { results } = useData();
     const ariaDisabled = useComputed(() => (results.value.items.length === 0 ? 'true' : 'false'));
     const title = useComputed(() => (results.value.items.length === 0 ? t('delete_none') : ''));
     return (
         <div class={styles.controls}>
-            <button class={styles.largeButton} data-action={BTN_ACTION_DELETE_ALL} aria-disabled={ariaDisabled} title={title}>
+            <button class={styles.largeButton} onClick={() => dispatch({ kind: 'delete-all' })} aria-disabled={ariaDisabled} title={title}>
                 <Trash />
                 <span>{buttonTxt}</span>
             </button>

special-pages/pages/history/app/components/Results.js

@@ -7,7 +7,7 @@ import { Empty } from './Empty.js';
 
 /**
  * @param {object} props
- * @param {import("@preact/signals").Signal<import("../global-state/GlobalStateProvider.js").Results>} props.results
+ * @param {import("@preact/signals").Signal<import("../global-state/DataProvider.js").Results>} props.results
  * @param {import("@preact/signals").Signal<Set<number>>} props.selected
  */
 export function Results({ results, selected }) {

special-pages/pages/history/app/components/SearchForm.js

@@ -1,7 +1,7 @@
 import styles from './Header.module.css';
 import { h } from 'preact';
-import { useTypedTranslation } from '../types.js';
-import { useComputed } from '@preact/signals';
+import { usePlatformName, useTypedTranslation } from '../types.js';
+import { useComputed, useSignalEffect } from '@preact/signals';
 import { SearchIcon } from '../icons/Search.js';
 import { useQueryDispatch } from '../global-state/QueryProvider.js';
 
@@ -16,6 +16,8 @@ export function SearchForm({ term, domain }) {
     const { t } = useTypedTranslation();
     const value = useComputed(() => term.value || domain.value || '');
     const dispatch = useQueryDispatch();
+    const platformName = usePlatformName();
+    useSearchShortcut(platformName);
 
     /**
      * @param {InputEvent} inputEvent
@@ -28,8 +30,16 @@ export function SearchForm({ term, domain }) {
         invariant(term !== undefined);
         dispatch({ kind: 'search-by-term', value: term });
     }
+
+    /**
+     * @param {SubmitEvent} submitEvent
+     */
+    function submit(submitEvent) {
+        console.log('todo: handle form submit?', submitEvent);
+    }
+
     return (
-        <form role="search">
+        <form role="search" onSubmit={submit}>
             <label class={styles.label}>
                 <span class="sr-only">{t('search_your_history')}</span>
                 <span class={styles.searchIcon}>
@@ -52,6 +62,37 @@ export function SearchForm({ term, domain }) {
     );
 }
 
+/**
+ * Listens for keyboard shortcuts to focus the search input.
+ *
+ * Handles platform-specific shortcuts for MacOS (Cmd+F) and Windows (Ctrl+F).
+ * If the shortcut is triggered, it will prevent the default action and focus
+ * on the first `input[type="search"]` element in the DOM, if available.
+ *
+ * @param {'macos' | 'windows'} platformName - Defines the current platform to handle the appropriate shortcut.
+ */
+function useSearchShortcut(platformName) {
+    useSignalEffect(() => {
+        const keydown = (e) => {
+            const isMacOS = platformName === 'macos';
+            const isFindShortcutMacOS = isMacOS && e.metaKey && e.key === 'f';
+            const isFindShortcutWindows = !isMacOS && e.ctrlKey && e.key === 'f';
+
+            if (isFindShortcutMacOS || isFindShortcutWindows) {
+                e.preventDefault();
+                const searchInput = /** @type {HTMLInputElement|null} */ (document.querySelector(`input[type="search"]`));
+                if (searchInput) {
+                    searchInput.focus();
+                }
+            }
+        };
+        document.addEventListener('keydown', keydown);
+        return () => {
+            document.removeEventListener('keydown', keydown);
+        };
+    });
+}
+
 /**
  * @param {any} condition
  * @param {string} [message]

special-pages/pages/history/app/components/Sidebar.js

@@ -6,10 +6,10 @@ import { useTypedTranslation } from '../types.js';
 import { Trash } from '../icons/Trash.js';
 import { useTypedTranslationWith } from '../../../new-tab/app/types.js';
 import { useQueryContext, useQueryDispatch } from '../global-state/QueryProvider.js';
-import { BTN_ACTION_DELETE_RANGE } from '../constants.js';
-import { useGlobalState } from '../global-state/GlobalStateProvider.js';
+import { useData } from '../global-state/DataProvider.js';
 import { toRange } from '../history.service.js';
 import { memo } from 'preact/compat';
+import { useHistoryServiceDispatch } from '../global-state/HistoryServiceProvider.js';
 
 /**
  * @import json from "../strings.json"
@@ -56,7 +56,7 @@ export function Sidebar({ ranges }) {
     const { t } = useTypedTranslation();
     const search = useQueryContext();
     const current = useComputed(() => search.value.range);
-    const { results } = useGlobalState();
+    const { results } = useData();
     const count = useComputed(() => results.value.items.length);
     const dispatch = useQueryDispatch();
 
@@ -78,6 +78,7 @@ export function Sidebar({ ranges }) {
             console.warn('could not determine valid range');
         }
     }
+
     return (
         <div class={styles.stack}>
             <h1 class={styles.pageTitle}>{t('page_title')}</h1>
@@ -101,6 +102,7 @@ const SidebarItem = memo(SidebarItem_);
  */
 function SidebarItem_({ range, title, current, count }) {
     const { t } = useTypedTranslationWith(/** @type {json} */ ({}));
+    const dispatch = useHistoryServiceDispatch();
     const ariaDisabled = useComputed(() => {
         return range === 'all' && count.value === 0 ? 'true' : 'false';
     });
@@ -140,7 +142,7 @@ function SidebarItem_({ range, title, current, count }) {
             </a>
             <button
                 class={styles.delete}
-                data-action={BTN_ACTION_DELETE_RANGE}
+                onClick={() => dispatch({ kind: 'delete-range', value: range })}
                 aria-label={deleteLabel}
                 tabindex={0}
                 value={range}

special-pages/pages/history/app/constants.js

@@ -3,11 +3,5 @@ export const OVERSCAN_AMOUNT = 5;
 export const BTN_ACTION_TITLE_MENU = 'title_menu';
 export const BTN_ACTION_ENTRIES_MENU = 'entries_menu';
 export const BTN_ACTION_DELETE_RANGE = 'deleteRange';
-export const BTN_ACTION_DELETE_ALL = 'deleteAll';
-export const KNOWN_ACTIONS = /** @type {const} */ ([
-    BTN_ACTION_TITLE_MENU,
-    BTN_ACTION_ENTRIES_MENU,
-    BTN_ACTION_DELETE_RANGE,
-    BTN_ACTION_DELETE_ALL,
-]);
+export const KNOWN_ACTIONS = /** @type {const} */ ([BTN_ACTION_TITLE_MENU, BTN_ACTION_ENTRIES_MENU, BTN_ACTION_DELETE_RANGE]);
 export const EVENT_RANGE_CHANGE = 'range-change';

special-pages/pages/history/app/global-state/GlobalStateProvider.js renamed to special-pages/pages/history/app/global-state/DataProvider.js

@@ -1,7 +1,8 @@
 import { h, createContext } from 'preact';
 import { useContext } from 'preact/hooks';
-import { batch, signal, useSignal, useSignalEffect } from '@preact/signals';
+import { signal, useSignal, useSignalEffect } from '@preact/signals';
 import { generateHeights } from '../utils.js';
+import { useQueryContext } from './QueryProvider.js';
 
 /**
  * @typedef {object} Results
@@ -12,40 +13,34 @@ import { generateHeights } from '../utils.js';
  * @typedef {import('../../types/history.ts').Range} Range
  */
 
-const GlobalState = createContext({
+const DataState = createContext({
     ranges: signal(/** @type {import('../history.service.js').Range[]} */ ([])),
-    term: signal(''),
     results: signal(/** @type {Results} */ ({})),
 });
 
 /**
- * Provides a global state context for the application.
+ * Provides a global state context for the application data.
  *
  * @param {Object} props
  * @param {import('../history.service.js').HistoryService} props.service - An instance of the history service to manage state updates.
  * @param {import('../history.service.js').ServiceData} props.initial - The initial state data for the history service.
  * @param {import('preact').ComponentChildren} props.children
  */
-export function GlobalStateProvider({ service, initial, children }) {
+export function DataProvider({ service, initial, children }) {
     // NOTE: These states will get extracted out later, once I know all the use-cases
     const ranges = useSignal(initial.ranges.ranges);
-    const term = useSignal('term' in initial.query.info.query ? initial.query.info.query.term : '');
+    const query = useQueryContext();
     const results = useSignal({
         items: initial.query.results,
         heights: generateHeights(initial.query.results),
     });
 
     useSignalEffect(() => {
         const unsub = service.onResults((data) => {
-            batch(() => {
-                if ('term' in data.info.query && data.info.query.term !== null) {
-                    term.value = data.info.query.term;
-                }
-                results.value = {
-                    items: data.results,
-                    heights: generateHeights(data.results),
-                };
-            });
+            results.value = {
+                items: data.results,
+                heights: generateHeights(data.results),
+            };
         });
 
         // Subscribe to changes in the 'ranges' data and reflect the updates into the UI
@@ -59,17 +54,18 @@ export function GlobalStateProvider({ service, initial, children }) {
     });
 
     useSignalEffect(() => {
-        return term.subscribe(() => {
+        return query.subscribe(() => {
+            // whenever the query changes, scroll the main container back to the top
             document.querySelector('[data-main-scroller]')?.scrollTo(0, 0);
         });
     });
 
-    return <GlobalState.Provider value={{ ranges, term, results }}>{children}</GlobalState.Provider>;
+    return <DataState.Provider value={{ ranges, results }}>{children}</DataState.Provider>;
 }
 
 // Hook for consuming the context
-export function useGlobalState() {
-    const context = useContext(GlobalState);
+export function useData() {
+    const context = useContext(DataState);
     if (!context) {
         throw new Error('useSelection must be used within a SelectionProvider');
     }