frontend/aria: ARIA for app itself, phase 12/P1

Author: haraldschilly

src/dev/ARIA.md

@@ -69,6 +69,65 @@ The frontend has a **three-level hierarchy**:
 - Sections with counts: `"Projects list (5 total)"`, `"Issues (2e 1w): {path}"`
 - Conditional content: Update aria-label when content changes
 
+### Pattern: Keyboard Accessibility for Custom Interactive Elements
+
+When creating interactive elements with `role="button"`, `role="tab"`, or other interactive roles using `<div>` or other non-button elements, you must provide keyboard support via the `ariaKeyDown` utility from `@cocalc/frontend/app/aria`.
+
+**Why this is needed:**
+
+- Native `<button>` elements support Enter and Space keys automatically
+- Custom elements with `role="button"` do not have native keyboard support
+- Screen reader users and keyboard-only users rely on this keyboard behavior
+
+**Usage pattern:**
+
+```tsx
+import { ariaKeyDown } from "@cocalc/frontend/app/aria";
+
+// For button-like divs
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={ariaKeyDown(handleClick)}
+  aria-label="Delete item"
+>
+  Delete
+</div>
+
+// For tab-like divs
+<div
+  role="tab"
+  tabIndex={0}
+  onClick={handleSelect}
+  onKeyDown={ariaKeyDown(handleSelect)}
+  aria-selected={isActive}
+>
+  Tab label
+</div>
+```
+
+**What ariaKeyDown does:**
+
+- Activates the handler when Enter or Space keys are pressed
+- Prevents default browser behavior (form submission, page scroll)
+- Provides the same keyboard experience as native buttons
+- Single source of truth for this common accessibility pattern
+
+**Implementation note:**
+Always use `ariaKeyDown` when you have:
+
+- `role="button"`, `role="tab"`, or other interactive roles on non-button elements
+- An `onClick` handler that should also work with keyboard
+- A `tabIndex={0}` to make the element focusable
+
+See `packages/frontend/app/aria.tsx` for the implementation and usage in:
+
+- `packages/frontend/app/nav-tab.tsx` - Navigation tabs
+- `packages/frontend/app/connection-indicator.tsx` - Status indicator
+- `packages/frontend/app/notifications.tsx` - Notification badges
+- `packages/frontend/frame-editors/frame-tree/status-bar.tsx` - Status bar close button
+
 ## Split Editors with Multiple Frames
 
 When editors are split into multiple frames, use nested regions with clear labels:
@@ -412,8 +471,9 @@ Location: `packages/frontend/project/page/`
 **Completed** ✅:
 
 - [x] **page.tsx** - Main project workspace
-  - [x] Main content area: `<div role="main" aria-label="Content: {currentFilename}">` (line 389-392)
-  - [x] Activity bar sidebar: `<aside role="complementary" aria-label="Project activity bar">` (line 356-371)
+  - [x] Root container: `<div role="region" aria-label="Project: {projectTitle}">` (line 420-425)
+  - [x] Main content area: `<div role="main" aria-label="Content: {currentFilename}">` (line 395-404)
+  - [x] Activity bar sidebar: `<aside role="complementary" aria-label="Project activity bar">` (line 362-376)
   - [x] File tabs navigation: `<nav aria-label="Open files">` (line 307-313)
   - [x] Flyout sidebar: `<aside role="complementary" aria-label="Project sidebar">` (line 262-278)
 
@@ -503,28 +563,42 @@ Location: `packages/frontend/app/`
 - `packages/frontend/app/connection-indicator.tsx` - Status live region with i18n labels
 - `packages/frontend/i18n/common.ts` - Added labels.connected
 
-#### **P1 - Important Improvements** ⏳ PENDING
-
-- [ ] **active-content.tsx** - Content router
-  - [ ] Dynamic content: Announce when switching pages
-  - [ ] Loading states: `aria-busy` indication
-  - [ ] Error states: ARIA alert or live region
-
-- [ ] **Banners** - Informational/warning banners (5 files)
-  - [ ] All banners: `role="region" aria-label="..."`
-  - [ ] `i18n-banner.tsx` - Language selection
-  - [ ] `verify-email-banner.tsx` - Email verification
-  - [ ] `version-warning.tsx` - Version alerts
-  - [ ] `insecure-test-mode-banner.tsx` - Test mode warning
-  - [ ] `warnings.tsx` - Cookie/storage warnings
-
-- [ ] **Notifications** - Notification indicators
-  - [ ] Notification badges: `aria-label` with count
-  - [ ] Live region: `aria-live="polite"` for count changes
-
-- [ ] **projects-nav.tsx** - Project tabs navigation
-  - [ ] Container: `aria-label="Open projects"`
-  - [ ] Tab semantics already handled by Ant Design Tabs
+#### **P1 - Important Improvements** ✅ COMPLETED
+
+- [x] **active-content.tsx** - Content router
+  - [x] Decision: Each active content page should have its own aria-labels (not wrapped in single region)
+  - [x] Left as `<>{v}</>` - ProjectPage, ProjectsPage, AccountPage, etc. handle their own landmarks
+
+- [x] **Banners** - Informational/warning banners (5 files)
+  - [x] **i18n-banner.tsx** - `role="region" aria-label="Language selection" aria-live="polite"`
+  - [x] **verify-email-banner.tsx** - `aria-label="Email verification required"` on Modal
+  - [x] **version-warning.tsx** - `role="region" aria-label="Version warning"` with dynamic aria-live (assertive if critical)
+  - [x] **insecure-test-mode-banner.tsx** - `role="region" aria-label="Test mode warning" aria-live="assertive"` on Alert
+  - [x] **warnings.tsx** - Both CookieWarning and LocalStorageWarning:
+    - `role="region" aria-label="Cookie warning" aria-live="assertive"`
+    - `role="region" aria-label="Local storage warning" aria-live="assertive"`
+
+- [x] **notifications.tsx** - Notification indicators with keyboard support
+  - [x] Added `getAriaLabel()` function for dynamic labels:
+    - Bell: `"File use notifications: {count} new"`
+    - Notifications: `"Messages and mentions: {unreadMessages} unread, {count} mentions, {newsUnread} news"`
+  - [x] Added `role="button"` for keyboard accessibility
+  - [x] Added `aria-live="polite"` to announce count changes
+  - [x] Added `tabIndex={0}` and `onKeyDown` for Enter/Space activation
+
+- [x] **projects-nav.tsx** - Project tabs navigation
+  - [x] Added `aria-label="Open projects"` to Ant Design Tabs container
+  - [x] Tab semantics already handled by Ant Design Tabs component
+
+**Files Modified (P1)**:
+
+- `packages/frontend/app/i18n-banner.tsx`
+- `packages/frontend/app/verify-email-banner.tsx`
+- `packages/frontend/app/version-warning.tsx`
+- `packages/frontend/app/warnings.tsx`
+- `packages/frontend/app/insecure-test-mode-banner.tsx`
+- `packages/frontend/app/notifications.tsx`
+- `packages/frontend/projects/projects-nav.tsx`
 
 ### Phase 13: Forms & Settings ⏳ PENDING
 

src/packages/frontend/app/active-content.tsx

@@ -54,6 +54,7 @@ export const ActiveContent: React.FC = React.memo(() => {
   }, [is_logged_in, notSignedIn]);
 
   const v: React.JSX.Element[] = [];
+
   open_projects?.forEach((project_id: string) => {
     const is_active = project_id === active_top_tab;
     const x = <ProjectPage project_id={project_id} is_active={is_active} />;
@@ -64,7 +65,7 @@ export const ActiveContent: React.FC = React.memo(() => {
     v.push(
       <div key={project_id} className={cls}>
         {x}
-      </div>
+      </div>,
     );
   });
 
@@ -100,7 +101,7 @@ export const ActiveContent: React.FC = React.memo(() => {
             </A>
             .
           </Alert>
-        </div>
+        </div>,
       );
     }
   }

src/packages/frontend/app/aria.tsx

@@ -0,0 +1,72 @@
+/*
+ *  This file is part of CoCalc: Copyright © 2025 Sagemath, Inc.
+ *  License: MS-RSL – see LICENSE.md for details.
+ */
+
+/**
+ * ARIA Keyboard Activation Handler
+ *
+ * This module provides utilities for making custom interactive elements
+ * (divs, spans, etc. with role="button" or role="tab") fully accessible
+ * to keyboard users.
+ *
+ * Why this is needed:
+ * - Native HTML <button> elements work with Enter and Space keys automatically
+ * - When using <div role="button"> (common with styled frameworks), keyboard
+ *   support must be manually implemented
+ * - This handler provides the standard keyboard behavior expected by assistive
+ *   technology users and keyboard navigators
+ *
+ * Usage:
+ *   <div
+ *     role="button"
+ *     tabIndex={0}
+ *     onClick={handleClick}
+ *     onKeyDown={(e) => ariaKeyDown(e, handleClick)}
+ *   >
+ *     Click me or press Enter/Space
+ *   </div>
+ *
+ * Benefits:
+ * - Consistent keyboard behavior across custom interactive components
+ * - Works with Enter key (standard for buttons) and Space (acceptable alternative)
+ * - Prevents default browser behavior (e.g., page scroll on Space)
+ * - Single source of truth for this common accessibility pattern
+ */
+
+/**
+ * Create a keyboard event handler for ARIA interactive elements
+ *
+ * Returns a handler that activates click handlers when users press Enter or Space keys,
+ * mimicking native button behavior for custom interactive elements
+ * with role="button", role="tab", role="region", etc.
+ *
+ * @param handler - The click handler to invoke (typically your onClick function)
+ * @returns A keyboard event handler function
+ *
+ * @example
+ * // In your component:
+ * <div
+ *   role="button"
+ *   tabIndex={0}
+ *   onClick={handleDelete}
+ *   onKeyDown={ariaKeyDown(handleDelete)}
+ * >
+ *   Delete
+ * </div>
+ */
+export function ariaKeyDown(
+  handler: (e?: React.KeyboardEvent | React.MouseEvent) => void,
+): (e: React.KeyboardEvent) => void {
+  return (e: React.KeyboardEvent) => {
+    // Activate on Enter (standard button behavior) or Space (accessible alternative)
+    if (e.key === "Enter" || e.key === " ") {
+      // Prevent default browser behavior:
+      // - Enter: prevents form submission or other default actions
+      // - Space: prevents page scroll
+      e.preventDefault();
+      // Call the handler (usually onClick)
+      handler(e);
+    }
+  };
+}

src/packages/frontend/app/connection-indicator.tsx

@@ -15,6 +15,7 @@ import { Icon } from "@cocalc/frontend/components";
 import { labels } from "@cocalc/frontend/i18n";
 import track from "@cocalc/frontend/user-tracking";
 import { COLORS } from "@cocalc/util/theme";
+import { ariaKeyDown } from "./aria";
 import {
   FONT_SIZE_ICONS_NORMAL,
   PageStyle,
@@ -122,12 +123,7 @@ export const ConnectionIndicator: React.FC<Props> = React.memo(
         aria-busy={connection_status === "connecting"}
         style={outer_style}
         onClick={connection_click}
-        onKeyDown={(e) => {
-          if (e.key === "Enter" || e.key === " ") {
-            e.preventDefault();
-            connection_click();
-          }
-        }}
+        onKeyDown={ariaKeyDown(connection_click)}
         tabIndex={0}
       >
         {render_connection_status()}

src/packages/frontend/app/i18n-banner.tsx

@@ -87,7 +87,12 @@ export const I18NBanner: React.FC<{}> = () => {
   if (!loaded) return;
 
   return (
-    <div style={I18N_BANNER_STYLE}>
+    <div
+      role="region"
+      aria-label="Language selection"
+      aria-live="polite"
+      style={I18N_BANNER_STYLE}
+    >
       <Text strong>
         <Icon name={"translation-outlined"} /> Use <SiteName /> in a different
         language:

src/packages/frontend/app/insecure-test-mode-banner.tsx

@@ -7,6 +7,9 @@ export default function InsecureTestModeBanner() {
       banner
       type="warning"
       showIcon
+      role="region"
+      aria-label="Test mode warning"
+      aria-live="assertive"
       style={{ background: "darkred", color: "white" }}
       message={
         <div style={{ textAlign: "center" }}>

src/packages/frontend/app/nav-tab.tsx

@@ -9,6 +9,7 @@ import { CSS, React, useActions } from "@cocalc/frontend/app-framework";
 import { Icon, IconName } from "@cocalc/frontend/components";
 import track from "@cocalc/frontend/user-tracking";
 import { COLORS } from "@cocalc/util/theme";
+import { ariaKeyDown } from "./aria";
 import { TOP_BAR_ELEMENT_CLASS } from "./top-nav-consts";
 
 const ACTIVE_BG_COLOR = COLORS.TOP_BAR.ACTIVE;
@@ -143,12 +144,7 @@ export const NavTab: React.FC<Props> = React.memo((props: Props) => {
   return (
     <div
       onClick={onClick}
-      onKeyDown={(e) => {
-        if (e.key === "Enter" || e.key === " ") {
-          e.preventDefault();
-          onClick();
-        }
-      }}
+      onKeyDown={ariaKeyDown(onClick)}
       role={props.role ?? "button"}
       aria-label={props["aria-label"]}
       tabIndex={0}

src/packages/frontend/app/notifications.tsx

@@ -16,6 +16,7 @@ import { Icon } from "@cocalc/frontend/components";
 import { unreachable } from "@cocalc/util/misc";
 import { COLORS } from "@cocalc/util/theme";
 import track from "@cocalc/frontend/user-tracking";
+import { ariaKeyDown } from "./aria";
 import { PageStyle, TOP_BAR_ELEMENT_CLASS } from "./top-nav-consts";
 import { blur_active_element } from "./util";
 import { useEffect, useMemo } from "react";
@@ -148,8 +149,29 @@ export const Notification: React.FC<Props> = React.memo((props: Props) => {
 
   const className = TOP_BAR_ELEMENT_CLASS + (active ? " active" : "");
 
+  const getAriaLabel = (): string => {
+    switch (type) {
+      case "bell":
+        return `File use notifications: ${count} new`;
+      case "notifications":
+        return `Messages and mentions: ${unread_message_count} unread messages, ${count} mentions, ${news_unread} news items`;
+      default:
+        unreachable(type);
+        return "";
+    }
+  };
+
   return (
-    <div style={outer_style} onClick={onClick} className={className}>
+    <div
+      role="button"
+      aria-label={getAriaLabel()}
+      aria-live="polite"
+      tabIndex={0}
+      style={outer_style}
+      onClick={onClick}
+      onKeyDown={ariaKeyDown(onClick)}
+      className={className}
+    >
       <div style={inner_style}>{renderBadge()}</div>
     </div>
   );

src/packages/frontend/app/verify-email-banner.tsx

@@ -168,6 +168,7 @@ function VerifyEmailModal({
       open={true}
       onCancel={() => doDismiss()}
       footer={renderFooter()}
+      aria-label="Email verification required"
     >
       {renderBanner()}
     </Modal>

src/packages/frontend/app/version-warning.tsx

@@ -112,7 +112,12 @@ export default function VersionWarning() {
   }
 
   return (
-    <div style={style}>
+    <div
+      role="region"
+      aria-label="Version warning"
+      aria-live={version < minVersion ? "assertive" : "polite"}
+      style={style}
+    >
       {render_suggested()}
       {render_critical()}
     </div>