feat: improve/refactor focus handling (#17796)

* feat: improve focus

* test

* lint

* use modulus in loop

web/src/lib/actions/__test__/focus-trap.spec.ts

@@ -1,8 +1,11 @@
 import FocusTrapTest from '$lib/actions/__test__/focus-trap-test.svelte';
+import { setDefaultTabbleOptions } from '$lib/utils/focus-util';
 import { render, screen } from '@testing-library/svelte';
 import userEvent from '@testing-library/user-event';
 import { tick } from 'svelte';
 
+setDefaultTabbleOptions({ displayCheck: 'none' });
+
 describe('focusTrap action', () => {
   const user = userEvent.setup();
 
@@ -38,6 +41,7 @@ describe('focusTrap action', () => {
     const openButton = screen.getByText('Open');
 
     await user.click(openButton);
+    await tick();
     expect(document.activeElement).toEqual(screen.getByTestId('one'));
 
     screen.getByText('Close').click();

web/src/lib/actions/focus-trap.ts

@@ -1,5 +1,5 @@
 import { shortcuts } from '$lib/actions/shortcut';
-import { getFocusable } from '$lib/utils/focus-util';
+import { getTabbable } from '$lib/utils/focus-util';
 import { tick } from 'svelte';
 
 interface Options {
@@ -18,18 +18,21 @@ export function focusTrap(container: HTMLElement, options?: Options) {
     };
   };
 
-  const setInitialFocus = () => {
-    const focusableElement = getFocusable(container)[0];
-    // Use tick() to ensure focus trap works correctly inside <Portal />
-    void tick().then(() => focusableElement?.focus());
+  const setInitialFocus = async () => {
+    const focusableElement = getTabbable(container, false)[0];
+    if (focusableElement) {
+      // Use tick() to ensure focus trap works correctly inside <Portal />
+      await tick();
+      focusableElement?.focus();
+    }
   };
 
   if (withDefaults(options).active) {
-    setInitialFocus();
+    void setInitialFocus();
   }
 
   const getFocusableElements = () => {
-    const focusableElements = getFocusable(container);
+    const focusableElements = getTabbable(container);
     return [
       focusableElements.at(0), //
       focusableElements.at(-1),
@@ -67,7 +70,7 @@ export function focusTrap(container: HTMLElement, options?: Options) {
     update(newOptions?: Options) {
       options = newOptions;
       if (withDefaults(options).active) {
-        setInitialFocus();
+        void setInitialFocus();
       }
     },
     destroy() {

web/src/lib/components/assets/thumbnail/__test__/thumbnail.spec.ts

@@ -1,7 +1,8 @@
 import { getIntersectionObserverMock } from '$lib/__mocks__/intersection-observer.mock';
 import Thumbnail from '$lib/components/assets/thumbnail/thumbnail.svelte';
+import { getTabbable } from '$lib/utils/focus-util';
 import { assetFactory } from '@test-data/factories/asset-factory';
-import { fireEvent, render, screen } from '@testing-library/svelte';
+import { fireEvent, render } from '@testing-library/svelte';
 
 vi.hoisted(() => {
   Object.defineProperty(globalThis, 'matchMedia', {
@@ -31,51 +32,47 @@ describe('Thumbnail component', () => {
 
   it('should only contain a single tabbable element (the container)', () => {
     const asset = assetFactory.build({ originalPath: 'image.jpg', originalMimeType: 'image/jpeg' });
-    render(Thumbnail, {
+    const { baseElement } = render(Thumbnail, {
       asset,
-      focussed: false,
       selected: true,
     });
 
-    const container = screen.getByTestId('container-with-tabindex');
-    expect(container.getAttribute('tabindex')).toBe('0');
+    const container = baseElement.querySelector('[data-thumbnail-focus-container]');
+    expect(container).not.toBeNull();
+    expect(container!.getAttribute('tabindex')).toBe('0');
 
-    // This isn't capturing all tabbable elements, but should be the most likely ones. Mainly guarding against
-    // inserting extra tabbable elments in future in <Thumbnail/>
-    let allTabbableElements = screen.queryAllByRole('link');
-    allTabbableElements = allTabbableElements.concat(screen.queryAllByRole('checkbox'));
-    expect(allTabbableElements.length).toBeGreaterThan(0);
-    for (const tabbableElement of allTabbableElements) {
-      const testIdValue = tabbableElement.dataset.testid;
-      if (testIdValue === null || testIdValue !== 'container-with-tabindex') {
-        expect(tabbableElement.getAttribute('tabindex')).toBe('-1');
-      }
-    }
+    // Guarding against inserting extra tabbable elments in future in <Thumbnail/>
+    const tabbables = getTabbable(container!);
+    expect(tabbables.length).toBe(0);
   });
 
   it('handleFocus should be called on focus of container', async () => {
     const asset = assetFactory.build({ originalPath: 'image.jpg', originalMimeType: 'image/jpeg' });
     const handleFocusSpy = vi.fn();
-    render(Thumbnail, {
+    const { baseElement } = render(Thumbnail, {
       asset,
       handleFocus: handleFocusSpy,
     });
 
-    const container = screen.getByTestId('container-with-tabindex');
-    await fireEvent(container, new FocusEvent('focus'));
+    const container = baseElement.querySelector('[data-thumbnail-focus-container]');
+    expect(container).not.toBeNull();
+    await fireEvent(container as HTMLElement, new FocusEvent('focus'));
 
     expect(handleFocusSpy).toBeCalled();
   });
 
-  it('element will be focussed if not already', () => {
+  it('element will be focussed if not already', async () => {
     const asset = assetFactory.build({ originalPath: 'image.jpg', originalMimeType: 'image/jpeg' });
     const handleFocusSpy = vi.fn();
-    render(Thumbnail, {
+    const { baseElement } = render(Thumbnail, {
       asset,
-      focussed: true,
       handleFocus: handleFocusSpy,
     });
 
+    const container = baseElement.querySelector('[data-thumbnail-focus-container]');
+    expect(container).not.toBeNull();
+    await fireEvent(container as HTMLElement, new FocusEvent('focus'));
+
     expect(handleFocusSpy).toBeCalled();
   });
 });

web/src/lib/components/assets/thumbnail/thumbnail.svelte

@@ -19,7 +19,7 @@
   import { thumbhash } from '$lib/actions/thumbhash';
   import { authManager } from '$lib/managers/auth-manager.svelte';
   import { mobileDevice } from '$lib/stores/mobile-device.svelte';
-  import { getFocusable } from '$lib/utils/focus-util';
+  import { focusNext } from '$lib/utils/focus-util';
   import { currentUrlReplaceAssetId } from '$lib/utils/navigation';
   import { TUNABLES } from '$lib/utils/tunables';
   import { onMount } from 'svelte';
@@ -35,7 +35,6 @@
     thumbnailWidth?: number | undefined;
     thumbnailHeight?: number | undefined;
     selected?: boolean;
-    focussed?: boolean;
     selectionCandidate?: boolean;
     disabled?: boolean;
     disableLinkMouseOver?: boolean;
@@ -58,7 +57,6 @@
     thumbnailWidth = undefined,
     thumbnailHeight = undefined,
     selected = false,
-    focussed = false,
     selectionCandidate = false,
     disabled = false,
     disableLinkMouseOver = false,
@@ -79,17 +77,11 @@
   } = TUNABLES;
 
   let usingMobileDevice = $derived(mobileDevice.pointerCoarse);
-  let focussableElement: HTMLElement | undefined = $state();
+  let element: HTMLElement | undefined = $state();
   let mouseOver = $state(false);
   let loaded = $state(false);
   let thumbError = $state(false);
 
-  $effect(() => {
-    if (focussed && document.activeElement !== focussableElement) {
-      focussableElement?.focus();
-    }
-  });
-
   let width = $derived(thumbnailSize || thumbnailWidth || 235);
   let height = $derived(thumbnailSize || thumbnailHeight || 235);
 
@@ -236,31 +228,14 @@
       if (evt.key === 'x') {
         onSelect?.(asset);
       }
-      if (document.activeElement === focussableElement && evt.key === 'Escape') {
-        const focusable = getFocusable(document);
-        const index = focusable.indexOf(focussableElement);
-
-        let i = index + 1;
-        while (i !== index) {
-          const next = focusable[i];
-          if (next.dataset.thumbnailFocusContainer !== undefined) {
-            if (i === focusable.length - 1) {
-              i = 0;
-            } else {
-              i++;
-            }
-            continue;
-          }
-          next.focus();
-          break;
-        }
+      if (document.activeElement === element && evt.key === 'Escape') {
+        focusNext((element) => element.dataset.thumbnailFocusContainer === undefined, true);
       }
     }}
     onclick={handleClick}
-    bind:this={focussableElement}
+    bind:this={element}
     onfocus={handleFocus}
     data-thumbnail-focus-container
-    data-testid="container-with-tabindex"
     tabindex={0}
     role="link"
   >

web/src/lib/components/elements/buttons/skip-link.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { t } from 'svelte-i18n';
   import Button from './button.svelte';
+  import { getTabbable } from '$lib/utils/focus-util';
 
   interface Props {
     /**
@@ -23,7 +24,12 @@
 
   const moveFocus = () => {
     const targetEl = document.querySelector<HTMLElement>(target);
-    targetEl?.focus();
+    if (targetEl) {
+      const element = getTabbable(targetEl)[0];
+      if (element) {
+        element.focus();
+      }
+    }
   };
 
   const getBreakpoint = () => {

web/src/lib/components/photos-page/asset-date-group.svelte

@@ -100,9 +100,6 @@
     }
   };
 
-  const assetOnFocusHandler = (asset: AssetResponseDto) => {
-    assetInteraction.focussedAssetId = asset.id;
-  };
   function filterIntersecting<R extends { intersecting: boolean }>(intersectable: R[]) {
     return intersectable.filter((int) => int.intersecting);
   }
@@ -182,13 +179,11 @@
             {showArchiveIcon}
             {asset}
             {groupIndex}
-            focussed={assetInteraction.isFocussedAsset(asset.id)}
             onClick={(asset) => onClick(assetStore, dateGroup.getAssets(), dateGroup.groupTitle, asset)}
             onSelect={(asset) => assetSelectHandler(assetStore, asset, dateGroup.getAssets(), dateGroup.groupTitle)}
             onMouseEvent={() => assetMouseEventHandler(dateGroup.groupTitle, assetSnapshot(asset))}
             selected={assetInteraction.hasSelectedAsset(asset.id) || dateGroup.bucket.store.albumAssets.has(asset.id)}
             selectionCandidate={assetInteraction.hasSelectionCandidate(asset.id)}
-            handleFocus={() => assetOnFocusHandler(asset)}
             disabled={dateGroup.bucket.store.albumAssets.has(asset.id)}
             thumbnailWidth={position.width}
             thumbnailHeight={position.height}

web/src/lib/components/photos-page/asset-grid.svelte

@@ -26,6 +26,7 @@
   import type { UpdatePayload } from 'vite';
   import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
   import { mobileDevice } from '$lib/stores/mobile-device.svelte';
+  import { focusNext } from '$lib/utils/focus-util';
 
   interface Props {
     isSelectionMode?: boolean;
@@ -616,34 +617,8 @@
     }
   };
 
-  const focusNextAsset = async () => {
-    if (assetInteraction.focussedAssetId === null) {
-      const firstAsset = assetStore.getFirstAsset();
-      if (firstAsset) {
-        assetInteraction.focussedAssetId = firstAsset.id;
-      }
-    } else {
-      const focussedAsset = assetStore.getAssets().find((asset) => asset.id === assetInteraction.focussedAssetId);
-      if (focussedAsset) {
-        const nextAsset = await assetStore.getNextAsset(focussedAsset);
-        if (nextAsset) {
-          assetInteraction.focussedAssetId = nextAsset.id;
-        }
-      }
-    }
-  };
-
-  const focusPreviousAsset = async () => {
-    if (assetInteraction.focussedAssetId !== null) {
-      const focussedAsset = assetStore.getAssets().find((asset) => asset.id === assetInteraction.focussedAssetId);
-      if (focussedAsset) {
-        const previousAsset = await assetStore.getPreviousAsset(focussedAsset);
-        if (previousAsset) {
-          assetInteraction.focussedAssetId = previousAsset.id;
-        }
-      }
-    }
-  };
+  const focusNextAsset = () => focusNext((element) => element.dataset.thumbnailFocusContainer !== undefined, true);
+  const focusPreviousAsset = () => focusNext((element) => element.dataset.thumbnailFocusContainer !== undefined, false);
 
   let isTrashEnabled = $derived($featureFlags.loaded && $featureFlags.trash);
   let isEmpty = $derived(assetStore.isInitialized && assetStore.buckets.length === 0);

web/src/lib/components/shared-components/gallery-viewer/gallery-viewer.svelte

@@ -22,6 +22,7 @@
   import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
   import { debounce } from 'lodash-es';
   import { getJustifiedLayoutFromAssets, type CommonJustifiedLayout } from '$lib/utils/layout-utils';
+  import { focusNext } from '$lib/utils/focus-util';
 
   interface Props {
     assets: AssetResponseDto[];
@@ -259,25 +260,8 @@
     }
   };
 
-  const focusNextAsset = () => {
-    if (assetInteraction.focussedAssetId === null && assets.length > 0) {
-      assetInteraction.focussedAssetId = assets[0].id;
-    } else if (assetInteraction.focussedAssetId !== null && assets.length > 0) {
-      const currentIndex = assets.findIndex((a) => a.id === assetInteraction.focussedAssetId);
-      if (currentIndex !== -1 && currentIndex + 1 < assets.length) {
-        assetInteraction.focussedAssetId = assets[currentIndex + 1].id;
-      }
-    }
-  };
-
-  const focusPreviousAsset = () => {
-    if (assetInteraction.focussedAssetId !== null && assets.length > 0) {
-      const currentIndex = assets.findIndex((a) => a.id === assetInteraction.focussedAssetId);
-      if (currentIndex >= 1) {
-        assetInteraction.focussedAssetId = assets[currentIndex - 1].id;
-      }
-    }
-  };
+  const focusNextAsset = () => focusNext((element) => element.dataset.thumbnailFocusContainer !== undefined, true);
+  const focusPreviousAsset = () => focusNext((element) => element.dataset.thumbnailFocusContainer !== undefined, false);
 
   let shortcutList = $derived(
     (() => {
@@ -417,10 +401,6 @@
     }
   };
 
-  const assetOnFocusHandler = (asset: AssetResponseDto) => {
-    assetInteraction.focussedAssetId = asset.id;
-  };
-
   let isTrashEnabled = $derived($featureFlags.loaded && $featureFlags.trash);
   let idsSelectedAssets = $derived(assetInteraction.selectedAssets.map(({ id }) => id));
 
@@ -490,12 +470,10 @@
             }}
             onSelect={(asset) => handleSelectAssets(asset)}
             onMouseEvent={() => assetMouseEventHandler(asset)}
-            handleFocus={() => assetOnFocusHandler(asset)}
             {showArchiveIcon}
             {asset}
             selected={assetInteraction.hasSelectedAsset(asset.id)}
             selectionCandidate={assetInteraction.hasSelectionCandidate(asset.id)}
-            focussed={assetInteraction.isFocussedAsset(asset.id)}
             thumbnailWidth={layout.width}
             thumbnailHeight={layout.height}
           />

web/src/lib/components/shared-components/scrubber/scrubber.svelte

@@ -2,7 +2,7 @@
   import Icon from '$lib/components/elements/icon.svelte';
   import type { AssetStore, LiteBucket } from '$lib/stores/assets-store.svelte';
   import { mobileDevice } from '$lib/stores/mobile-device.svelte';
-  import { getFocusable } from '$lib/utils/focus-util';
+  import { getTabbable } from '$lib/utils/focus-util';
   import { fromLocalDateTime, type ScrubberListener } from '$lib/utils/timeline-util';
   import { mdiPlay } from '@mdi/js';
   import { clamp } from 'lodash-es';
@@ -376,7 +376,7 @@
     if (forward || backward) {
       event.preventDefault();
 
-      const focusable = getFocusable(document);
+      const focusable = getTabbable(document.body);
       if (scrollBar) {
         const index = focusable.indexOf(scrollBar);
         if (index !== -1) {

web/src/lib/stores/asset-interaction.svelte.ts

@@ -14,7 +14,6 @@ export class AssetInteraction {
     return this.assetSelectionCandidates.some((asset) => asset.id === assetId);
   }
   assetSelectionStart = $state<AssetResponseDto | null>(null);
-  focussedAssetId = $state<string | null>(null);
   selectionActive = $derived(this.selectedAssets.length > 0);
 
   private user = fromStore<UserAdminResponseDto | undefined>(user);
@@ -73,8 +72,4 @@ export class AssetInteraction {
     this.assetSelectionCandidates = [];
     this.assetSelectionStart = null;
   }
-
-  isFocussedAsset(assetId: string) {
-    return this.focussedAssetId === assetId;
-  }
 }

web/src/lib/utils/focus-util.ts

@@ -1,4 +1,39 @@
-const selectors =
-  'button:not([disabled], .hidden), [href]:not(.hidden), input:not([disabled], .hidden), select:not([disabled], .hidden), textarea:not([disabled], .hidden), [tabindex]:not([tabindex="-1"], .hidden)';
+import { focusable, isTabbable, tabbable, type CheckOptions, type TabbableOptions } from 'tabbable';
 
-export const getFocusable = (container: ParentNode) => [...container.querySelectorAll<HTMLElement>(selectors)];
+type TabbableOpts = TabbableOptions & CheckOptions;
+let defaultOpts: TabbableOpts = {
+  includeContainer: false,
+};
+
+export const setDefaultTabbleOptions = (options: TabbableOpts) => {
+  defaultOpts = options;
+};
+
+export const getTabbable = (container: Element, includeContainer: boolean = false) =>
+  tabbable(container, { ...defaultOpts, includeContainer });
+
+export const focusNext = (selector: (element: HTMLElement | SVGElement) => boolean, forwardDirection: boolean) => {
+  const focusElements = focusable(document.body, { includeContainer: true });
+  const current = document.activeElement as HTMLElement;
+  const index = focusElements.indexOf(current);
+  if (index === -1) {
+    for (const element of focusElements) {
+      if (selector(element)) {
+        element.focus();
+        return;
+      }
+    }
+    focusElements[0].focus();
+    return;
+  }
+  const totalElements = focusElements.length;
+  let i = index;
+  do {
+    i = (i + (forwardDirection ? 1 : -1) + totalElements) % totalElements;
+    const next = focusElements[i];
+    if (isTabbable(next) && selector(next)) {
+      next.focus();
+      break;
+    }
+  } while (i !== index);
+};