Skip to content

SHORTCUT_HINT_IMPLEMENTATION.md

Latest commit

 

History

History
117 lines (85 loc) · 4.77 KB

SHORTCUT_HINT_IMPLEMENTATION.md

File metadata and controls

117 lines (85 loc) · 4.77 KB
Raw

Shortcut Hint Chip Implementation - NotificationCenter

Summary

Implemented a subtle keyboard shortcut hint chip on the NotificationCenter for the "Mark all read" primary action as part of the GrantFox FWC26 campaign (Stellar Wave).

Changes Made

1. NotificationCenter.tsx

File: src/components/notifications/NotificationCenter.tsx

  • Import Addition: Added KbdHint component import
  • Keyboard Handler: Added useEffect hook to handle Shift+R keyboard shortcut when the notification panel is open
    • Only activates when there are unread notifications
    • Prevents default browser behavior
    • Calls handleMarkAllAsRead function
  • UI Enhancement: Added KbdHint component to the "Mark all read" button
    • Shows "Shift+R" shortcut in badge variant
    • Only displays when there are unread notifications (unreadCount > 0)
    • Includes proper aria-label for screen readers
    • Wrapped button content in span with .nc-btn-content class for proper spacing

2. NotificationCenter.css

File: src/components/notifications/NotificationCenter.css

  • Button Content Container: Added .nc-btn-content class for flex layout with gap
  • Shortcut Hint Styling: Added .nc-shortcut-hint class for font size adjustment
    • Ensures the hint chip is subtly sized (0.65rem) to not overwhelm the UI

3. ShortcutHelpOverlay.tsx

File: src/components/ShortcutHelpOverlay.tsx

  • Documentation Update: Added Shift+R shortcut to the Notifications section
    • Description: "Mark all notifications as read"
    • Ensures users can discover the shortcut via the help overlay (press ?)

4. NotificationCenter.test.tsx

File: src/components/notifications/NotificationCenter.test.tsx

Added comprehensive test coverage for the new feature:

  1. renders KbdHint shortcut chip when there are unread notifications

    • Verifies the Shift+R hint is visible when unread notifications exist

  2. does not render KbdHint shortcut chip when there are no unread notifications

    • Ensures the hint is hidden when all notifications are read

  3. activates mark all read with Shift+R keyboard shortcut

    • Tests the keyboard shortcut functionality
    • Verifies all notifications are marked as read after pressing Shift+R

  4. does not activate Shift+R shortcut when panel is closed

    • Ensures the shortcut only works when the notification panel is open

Accessibility Compliance (WCAG 2.1 AA)

  • Screen Reader Support: KbdHint component includes .sr-only element with descriptive text
  • Keyboard Navigation: Shortcut only works via keyboard (Shift+R), not mouse/touch
  • Focus Management: Existing focus trap and escape key handling preserved
  • ARIA Attributes: Proper aria-label on the hint chip for screen readers
  • Color Contrast: Uses design tokens from src/index.css for consistent theming
  • High Contrast Mode: KbdHint component supports [data-contrast="high"] adjustments

Responsive Design

  • Desktop (≥ 640px): Hint chip displays inline with button text
  • Mobile (≤ 640px): Hint chip scales appropriately with the button
  • Safe Areas: Mobile bottom sheet layout respects safe-area-insets
  • Touch Targets: Button maintains 44px minimum touch target (WCAG 2.5.5)

Design Token Consistency

All styling uses CSS custom properties from src/index.css:

  • --text, --muted for text colors
  • --surface-raised, --border for backgrounds and borders
  • --radius-sm, --radius-md for border radius
  • Dark mode and high contrast mode support via existing token system

API Changes

Public API

No breaking changes to public APIs. The NotificationCenter component interface remains unchanged.

Internal Changes

  • Added keyboard event listener for Shift+R shortcut (only when panel is open)
  • Added conditional rendering of KbdHint component based on unread count

Testing

Run the updated tests:

npm test -- src/components/notifications/NotificationCenter.test.tsx

All existing tests remain passing. New tests cover:

  • Shortcut hint visibility states
  • Keyboard shortcut activation
  • Edge case (panel closed)

Browser Compatibility

  • Modern browsers with ES6+ support
  • Keyboard event handling uses standard KeyboardEvent API
  • CSS custom properties supported in all modern browsers

Performance Considerations

  • Keyboard event listener only attached when panel is open (cleanup on unmount)
  • Conditional rendering of KbdHint component (only when unreadCount > 0)
  • No additional network requests or heavy computations

Future Enhancements

Potential improvements for future iterations:

  • Add user preference to disable keyboard shortcuts
  • Localize shortcut hint text for international users
  • Add visual feedback when shortcut is activated
  • Consider additional shortcuts for other notification actions (e.g., Clear all)