♿️(frontend) make participant pagination readable and keyboard reachable

Improves PaginationControl: clearer structure, keyboard nav, a11y improved.
The main room and the picture-in-picture window share this control.
Ctrl+Shift+G focuses the pagination.

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to
 - 🔧(summary) add setting to control Sentry traces sampling rate
 - ✨(frontend) let signed-out visitors start a meeting
 - ✨(backend) expose `allow_unregistered_rooms` in the frontend configuration
+- ♿️(frontend) make participant pagination readable and keyboard reachable #1775
 
 ### Changed
 
@@ -93,7 +94,7 @@ and this project adheres to
 
 ### Fixed
 
-- 🐛(helm) probe liveness on __lbheartbeat__ and readiness on __heartbeat__
+- 🐛(helm) probe liveness on **lbheartbeat** and readiness on **heartbeat**
 - 🐛(helm) render periodSeconds and failureThreshold on probes
 - 🐛(backend) report the app release to Sentry instead of "NA"
 - 🐛(frontend) play the waiting room notification sound on every arrival
@@ -165,6 +166,7 @@ and this project adheres to
 ### Added
 
 - ✨(any) let any authenticated user manage the lobby on trusted rooms
+
 ### Changed
 
 - 📱(frontend) collapse mobile control bar items on narrow viewports

src/frontend/src/features/layout/components/GridLayout.tsx

@@ -7,7 +7,6 @@ import {
   useSwipe,
 } from '@livekit/components-react'
 import { mergeProps } from '@/utils/mergeProps'
-import { PaginationIndicator } from './PaginationIndicator'
 import { useGridLayout } from '../hooks/useGridLayout'
 import { PaginationControl } from './PaginationControl'
 import { useSpeakerPromotionTrigger } from '../hooks/useSpeakerPromotionTrigger'
@@ -62,13 +61,7 @@ export function GridLayout({ tracks, ...props }: GridLayoutProps) {
     >
       <TrackLoop tracks={pagination.tracks}>{props.children}</TrackLoop>
       {tracks.length > layout.maxTiles && (
-        <>
-          <PaginationIndicator
-            totalPageCount={pagination.totalPageCount}
-            currentPage={pagination.currentPage}
-          />
-          <PaginationControl pagesContainer={gridEl} {...pagination} />
-        </>
+        <PaginationControl {...pagination} focusShortcut />
       )}
     </div>
   )

src/frontend/src/features/layout/components/PaginationControl.tsx

@@ -1,99 +1,145 @@
-import * as React from 'react'
-import { createInteractingObservable } from '@livekit/components-core'
 import { RiArrowLeftSLine, RiArrowRightSLine } from '@remixicon/react'
 import { Button } from '@/primitives'
-import { useEffect, useState } from 'react'
 import { useTranslation } from 'react-i18next'
-import { css } from '@/styled-system/css'
+import { css, cva, type RecipeVariantProps } from '@/styled-system/css'
+import { useCallback, useRef } from 'react'
+import { useRegisterKeyboardShortcut } from '@/features/shortcuts/useRegisterKeyboardShortcut'
 
-export interface PaginationControlProps {
+const paginationToolbar = cva({
+  base: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '0.125rem',
+    backgroundColor: 'primaryDark.50',
+    borderRadius: '2rem',
+    border: '1px solid',
+    borderColor: 'primaryDark.200',
+    padding: '0.375rem',
+  },
+  variants: {
+    placement: {
+      overlay: {
+        position: 'absolute',
+        bottom: '1rem',
+        left: '50%',
+        zIndex: 2,
+        transform: 'translateX(-50%)',
+        boxShadow: '0 2px 10px rgba(0, 0, 0, 0.45)',
+      },
+      inline: {
+        alignSelf: 'center',
+        flexShrink: 0,
+        marginTop: '1rem',
+      },
+    },
+  },
+  defaultVariants: {
+    placement: 'overlay',
+  },
+})
+
+export type PaginationControlProps = RecipeVariantProps<
+  typeof paginationToolbar
+> & {
   totalPageCount: number
   nextPage: () => void
   prevPage: () => void
   currentPage: number
-  pagesContainer?: React.RefObject<HTMLElement>
+  // The shortcut listens on the main window only, so a single instance may own it.
+  focusShortcut?: boolean
 }
 
+const arrowButtonClass = css({
+  _disabled: {
+    cursor: 'default',
+    backgroundColor: 'transparent !important',
+    '& svg': {
+      opacity: 0.35,
+    },
+    _focusVisible: {
+      outline: '2px solid',
+      outlineColor: 'focusRing',
+      outlineOffset: '2px',
+    },
+  },
+})
+
 export function PaginationControl({
   totalPageCount,
   nextPage,
   prevPage,
   currentPage,
-  pagesContainer: connectedElement,
+  placement,
+  focusShortcut = false,
 }: PaginationControlProps) {
   const { t } = useTranslation('rooms', { keyPrefix: 'pagination' })
-  const [interactive, setInteractive] = useState(false)
+  const prevButtonRef = useRef<HTMLButtonElement>(null)
+  const nextButtonRef = useRef<HTMLButtonElement>(null)
+  const isFirstPage = currentPage <= 1
+  const isLastPage = currentPage >= totalPageCount
 
-  useEffect(() => {
-    let subscription:
-      | ReturnType<ReturnType<typeof createInteractingObservable>['subscribe']>
-      | undefined
-    if (connectedElement) {
-      subscription = createInteractingObservable(
-        connectedElement.current,
-        2000
-      ).subscribe(setInteractive)
-    }
-    return () => {
-      if (subscription) {
-        subscription.unsubscribe()
-      }
-    }
-  }, [connectedElement])
+  const focusPagination = useCallback(() => {
+    const target = isLastPage ? prevButtonRef.current : nextButtonRef.current
+    target?.focus()
+  }, [isLastPage])
+
+  useRegisterKeyboardShortcut({
+    id: focusShortcut ? 'focus-pagination' : undefined,
+    handler: focusPagination,
+    isDisabled: totalPageCount <= 1,
+  })
 
   if (totalPageCount <= 1) return null
 
+  const pageCount = t('count', { currentPage, totalPageCount })
+
   return (
-    <nav
-      aria-label={t('label')}
-      className={css({
-        position: 'absolute',
-        bottom: '1rem',
-        left: '50%',
-        transform: 'translateX(-50%)',
-        alignItems: 'stretch',
-        backgroundColor: 'var(--lk-control-bg)',
-        borderRadius: 'var(--lk-border-radius)',
-        transition: 'opacity ease-in-out .15s',
-        display: 'none',
-        border: '1px solid',
-        borderColor: 'primaryDark.100',
-        overflow: 'hidden',
-      })}
-      style={{
-        display: interactive ? 'flex' : 'none',
-      }}
-      data-lk-user-interaction={interactive}
+    <div
+      role="group"
+      aria-label={`${t('label')}, ${pageCount}`}
+      className={paginationToolbar({ placement })}
     >
       <Button
-        isDisabled={currentPage == 1}
-        onPress={prevPage}
-        size="xs"
-        variant="quaternaryText"
+        ref={prevButtonRef}
+        aria-disabled={isFirstPage}
+        onPress={isFirstPage ? undefined : prevPage}
+        size="sm"
+        square
+        variant="primaryTextDark"
+        className={arrowButtonClass}
         aria-label={t('previous')}
+        tooltip={t('previous')}
       >
-        <RiArrowLeftSLine />
+        <RiArrowLeftSLine size={20} />
       </Button>
       <span
         role="status"
         className={css({
-          padding: '0.25rem 0.5rem',
+          color: 'white',
+          fontSize: '0.8125rem',
+          fontWeight: 500,
+          minWidth: '3.5rem',
+          textAlign: 'center',
+          userSelect: 'none',
+          padding: '0 0.35rem',
+          whiteSpace: 'nowrap',
         })}
       >
-        {t('count', {
-          currentPage,
-          totalPageCount,
-        })}
+        {pageCount}
       </span>
       <Button
-        isDisabled={currentPage == totalPageCount}
-        onPress={nextPage}
-        size="xs"
-        variant="quaternaryText"
+        ref={nextButtonRef}
+        aria-disabled={isLastPage}
+        onPress={isLastPage ? undefined : nextPage}
+        size="sm"
+        square
+        variant="primaryTextDark"
+        className={arrowButtonClass}
         aria-label={t('next')}
+        tooltip={t('next')}
       >
-        <RiArrowRightSLine />
+        <RiArrowRightSLine size={20} />
       </Button>
-    </nav>
+    </div>
   )
 }

src/frontend/src/features/layout/components/PaginationIndicator.tsx

@@ -1,30 +0,0 @@
-import * as React from 'react'
-
-export interface PaginationIndicatorProps {
-  totalPageCount: number
-  currentPage: number
-}
-
-export const PaginationIndicator: (
-  props: PaginationIndicatorProps & React.RefAttributes<HTMLDivElement>
-) => React.ReactNode = /* @__PURE__ */ React.forwardRef<
-  HTMLDivElement,
-  PaginationIndicatorProps
->(function PaginationIndicator(
-  { totalPageCount, currentPage }: PaginationIndicatorProps,
-  ref
-) {
-  const bubbles = new Array(totalPageCount).fill('').map((_, index) => {
-    if (index + 1 === currentPage) {
-      return <span data-lk-active key={index} />
-    } else {
-      return <span key={index} />
-    }
-  })
-
-  return (
-    <div ref={ref} className="lk-pagination-indicator" aria-hidden="true">
-      {bubbles}
-    </div>
-  )
-})

src/frontend/src/features/pip/components/layout/PipPagination.tsx

@@ -1,96 +0,0 @@
-import { RiArrowLeftSLine, RiArrowRightSLine } from '@remixicon/react'
-import { useTranslation } from 'react-i18next'
-import { styled } from '@/styled-system/jsx'
-
-interface PipPaginationProps {
-  totalPageCount: number
-  currentPage: number
-  nextPage: () => void
-  prevPage: () => void
-}
-
-export const PipPagination = ({
-  totalPageCount,
-  currentPage,
-  nextPage,
-  prevPage,
-}: PipPaginationProps) => {
-  const { t } = useTranslation('rooms', { keyPrefix: 'pagination' })
-
-  if (totalPageCount <= 1) return null
-
-  return (
-    <Nav aria-label={t('label')}>
-      <ArrowButton
-        type="button"
-        onClick={prevPage}
-        disabled={currentPage === 1}
-        aria-label={t('previous')}
-      >
-        <RiArrowLeftSLine size={18} />
-      </ArrowButton>
-      <Counter role="status">
-        {t('count', { currentPage, totalPageCount })}
-      </Counter>
-      <ArrowButton
-        type="button"
-        onClick={nextPage}
-        disabled={currentPage === totalPageCount}
-        aria-label={t('next')}
-      >
-        <RiArrowRightSLine size={18} />
-      </ArrowButton>
-    </Nav>
-  )
-}
-
-const Nav = styled('nav', {
-  base: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: '0.25rem',
-    marginTop: '1rem',
-    flexShrink: 0,
-  },
-})
-
-const ArrowButton = styled('button', {
-  base: {
-    display: 'inline-flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    width: '1.75rem',
-    height: '1.75rem',
-    borderRadius: '4px',
-    border: 'none',
-    cursor: 'pointer',
-    color: 'white',
-    backgroundColor: 'primaryDark.100',
-    transition: 'opacity 0.15s, background-color 0.15s',
-    '&:hover:not(:disabled)': {
-      backgroundColor: 'primaryDark.75',
-    },
-    '&:focus-visible': {
-      outline: '2px solid',
-      outlineColor: 'white',
-      outlineOffset: '2px',
-    },
-    '&:disabled': {
-      opacity: 0.3,
-      cursor: 'default',
-    },
-  },
-})
-
-const Counter = styled('span', {
-  base: {
-    fontSize: '0.75rem',
-    color: 'white',
-    opacity: 0.8,
-    whiteSpace: 'nowrap',
-    padding: '0 0.25rem',
-    minWidth: '3rem',
-    textAlign: 'center',
-  },
-})

src/frontend/src/features/pip/components/layout/PipStage.tsx

@@ -4,7 +4,7 @@ import { RoomEvent, Track } from 'livekit-client'
 import { styled } from '@/styled-system/jsx'
 import { PipFocusLayout } from './PipFocusLayout'
 import { PipGridLayout } from './PipGridLayout'
-import { PipPagination } from './PipPagination'
+import { PaginationControl } from '@/features/layout/components/PaginationControl'
 import { PipScreenShareLayout } from './PipScreenShareLayout'
 import { StageFrame } from './StageFrame'
 import { MAX_PIP_TILES } from '../../utils/pipGrid'
@@ -120,12 +120,7 @@ const PaginatedStage = ({
 }) => (
   <StageWrapper>
     <StageFrame>{children}</StageFrame>
-    <PipPagination
-      totalPageCount={pagination.totalPageCount}
-      currentPage={pagination.currentPage}
-      nextPage={pagination.nextPage}
-      prevPage={pagination.prevPage}
-    />
+    <PaginationControl {...pagination} placement="inline" />
   </StageWrapper>
 )
 

src/frontend/src/features/shortcuts/catalog.ts

@@ -7,6 +7,7 @@ export type ShortcutCategory = 'navigation' | 'media' | 'interaction'
 export type ShortcutId =
   | 'open-shortcuts'
   | 'focus-toolbar'
+  | 'focus-pagination'
   | 'toggle-microphone'
   | 'toggle-camera'
   | 'push-to-talk'
@@ -44,6 +45,11 @@ export const shortcutCatalog: ShortcutDescriptor[] = [
     category: 'navigation',
     shortcut: { key: 'F2' },
   },
+  {
+    id: 'focus-pagination',
+    category: 'navigation',
+    shortcut: { key: 'G', ctrlKey: true, shiftKey: true },
+  },
   {
     id: 'toggle-microphone',
     category: 'media',

src/frontend/src/features/shortcuts/useRegisterKeyboardShortcut.ts

@@ -21,8 +21,13 @@ export const useRegisterKeyboardShortcut = ({
     const formattedKey = formatShortcutKey(descriptor.shortcut)
     if (isDisabled) {
       keyboardShortcutsStore.shortcuts.delete(formattedKey)
-    } else {
-      keyboardShortcutsStore.shortcuts.set(formattedKey, handler)
+      return
+    }
+    keyboardShortcutsStore.shortcuts.set(formattedKey, handler)
+    return () => {
+      if (keyboardShortcutsStore.shortcuts.get(formattedKey) === handler) {
+        keyboardShortcutsStore.shortcuts.delete(formattedKey)
+      }
     }
   }, [handler, id, isDisabled])
 }

src/frontend/src/locales/de/rooms.json

@@ -784,6 +784,7 @@
     "actions": {
       "open-shortcuts": "Tastenkürzel-Hilfe öffnen",
       "focus-toolbar": "Fokus auf die untere Symbolleiste",
+      "focus-pagination": "Fokus auf die Teilnehmerseiten",
       "toggle-microphone": "Mikrofon umschalten",
       "toggle-camera": "Kamera umschalten",
       "push-to-talk": "Push-to-talk",

src/frontend/src/locales/en/rooms.json

@@ -784,6 +784,7 @@
     "actions": {
       "open-shortcuts": "Open shortcuts help",
       "focus-toolbar": "Focus bottom toolbar",
+      "focus-pagination": "Focus participant pagination",
       "toggle-microphone": "Toggle microphone",
       "toggle-camera": "Toggle camera",
       "push-to-talk": "Push-to-talk (hold to unmute)",

src/frontend/src/locales/es/rooms.json

@@ -783,6 +783,7 @@
     "actions": {
       "open-shortcuts": "Abrir la ayuda de atajos",
       "focus-toolbar": "Poner el foco en la barra de herramientas inferior",
+      "focus-pagination": "Poner el foco en la paginación de participantes",
       "toggle-microphone": "Activar o desactivar el micrófono",
       "toggle-camera": "Activar o desactivar la cámara",
       "push-to-talk": "Pulsar para hablar (mantener para reactivar)",

src/frontend/src/locales/fr/rooms.json

@@ -784,6 +784,7 @@
     "actions": {
       "open-shortcuts": "Ouvrir l’aide des raccourcis",
       "focus-toolbar": "Mettre le focus sur la barre d’outils du bas",
+      "focus-pagination": "Mettre le focus sur la pagination des participants",
       "toggle-microphone": "Activer ou désactiver le micro",
       "toggle-camera": "Activer ou désactiver la caméra",
       "push-to-talk": "Appuyer pour parler (maintenir pour réactiver)",

src/frontend/src/locales/nl/rooms.json

@@ -784,6 +784,7 @@
     "actions": {
       "open-shortcuts": "Sneltoetsenhulp openen",
       "focus-toolbar": "Focus op de onderste werkbalk",
+      "focus-pagination": "Focus op de paginering van deelnemers",
       "toggle-microphone": "Microfoon aan/uit",
       "toggle-camera": "Camera aan/uit",
       "push-to-talk": "Push-to-talk (ingedrukt houden om te activeren)",