frontend/aria: Complete Phase 10 - Editor Frame Infrastructure

haraldschilly · claude · haraldschilly · commit 2ece11297663 · 2025-10-28T14:13:51.000+01:00
Enhanced ARIA accessibility for the core editor frame system (Phase 10) with comprehensive landmark labels and live region support: **Frame Tree System (title-bar.tsx)**: - Menu navigation: Changed div to <nav> with aria-label - Frame controls region: Added role="region" with layout controls label - Symbol/outline bar: Added role="region" with descriptive label - Control buttons: Added aria-labels to split, maximize, minimize, close buttons - Connection status: Added aria-live="polite" for real-time updates - All buttons: Added aria-expanded for dynamic state indication **Editor Container (editor.tsx)**: - Added role="application" with context-aware aria-label including editor type and path - Enables proper keyboard navigation and focus management **Status Bar (status-bar.tsx)**: - Converted to ARIA live region with role="status" - Added aria-live="polite" and aria-atomic="true" for status announcements - Made clear button keyboard accessible **Icon Component Enhancement (components/icon.tsx)**: - Added ARIA attribute support (role, aria-label, aria-expanded, aria-pressed, aria-live, tabIndex) - Enables Icon to be used with accessibility roles like "button" - Updated unicode and icon rendering paths to pass ARIA attributes **Testing**: - Build successful: pnpm build-dev in packages/static ✅ 🧠 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/src/dev/ARIA.md b/src/dev/ARIA.md
diff --git a/src/packages/frontend/account/account-page.tsx b/src/packages/frontend/account/account-page.tsx
@@ -555,8 +555,14 @@ export const AccountPage: React.FC = () => {
     }
 
     return (
-      <div className="smc-vfill" style={{ flexDirection: "row" }}>
-        <div
+      <main
+        className="smc-vfill"
+        style={{ flexDirection: "row" }}
+        role="main"
+        aria-label="Account settings"
+      >
+        <nav
+          aria-label="Account settings menu"
           style={{
             background: "#00000005",
             borderRight: "1px solid rgba(5, 5, 5, 0.06)",
@@ -598,6 +604,7 @@ export const AccountPage: React.FC = () => {
               color: COLORS.GRAY_M,
             }}
             onClick={handleHideToggle}
+            aria-label={hidden ? "Expand menu" : "Collapse menu"}
             icon={
               <Icon
                 name={
@@ -608,9 +615,15 @@ export const AccountPage: React.FC = () => {
           >
             {hidden ? "" : "Hide"}
           </Button>
-        </div>
+        </nav>
         <div
           className="smc-vfill"
+          role="region"
+          aria-label={
+            active_page === "preferences" && active_sub_tab
+              ? `${titles[active_sub_tab]?.props?.children?.[1] || active_sub_tab} settings`
+              : `${titles[active_page]?.props?.children?.[1] || active_page} settings`
+          }
           style={{
             overflow: "auto",
             paddingLeft: "15px",
@@ -627,12 +640,12 @@ export const AccountPage: React.FC = () => {
             : children[active_page]}
           <Footer />
         </div>
-      </div>
+      </main>
     );
   }
 
   return (
-    <div className="smc-vfill">
+    <div className="smc-vfill" role="main" aria-label="Account page">
       {is_logged_in && !get_api_key ? (
         render_logged_in_view()
       ) : (
diff --git a/src/packages/frontend/account/account-preferences-ai.tsx b/src/packages/frontend/account/account-preferences-ai.tsx
@@ -12,13 +12,15 @@ export function AccountPreferencesAI() {
   const kucalc = useTypedRedux("customize", "kucalc");
 
   return (
-    <OtherSettings
-      other_settings={other_settings}
-      is_stripe_customer={
-        !!stripe_customer?.getIn(["subscriptions", "total_count"])
-      }
-      kucalc={kucalc}
-      mode="ai"
-    />
+    <div role="region" aria-label="AI settings">
+      <OtherSettings
+        other_settings={other_settings}
+        is_stripe_customer={
+          !!stripe_customer?.getIn(["subscriptions", "total_count"])
+        }
+        kucalc={kucalc}
+        mode="ai"
+      />
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences-appearance.tsx b/src/packages/frontend/account/account-preferences-appearance.tsx
@@ -292,7 +292,7 @@ export function AccountPreferencesAppearance() {
   }
 
   return (
-    <>
+    <div role="region" aria-label="Appearance settings">
       {renderUserInterfacePanel()}
       <OtherSettings
         other_settings={other_settings}
@@ -311,6 +311,6 @@ export function AccountPreferencesAppearance() {
         font_size={font_size}
       />
       <TerminalSettings />
-    </>
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences-communication.tsx b/src/packages/frontend/account/account-preferences-communication.tsx
@@ -114,18 +114,20 @@ export function AccountPreferencesCommunication(): React.JSX.Element {
   }
 
   return (
-    <Panel
-      size="small"
-      header={
-        <>
-          <Icon name={COMMUNICATION_ICON_NAME} />{" "}
-          {intl.formatMessage(labels.communication)}
-        </>
-      }
-    >
-      {render_global_banner()}
-      {render_no_free_warnings()}
-      {render_no_email_new_messages()}
-    </Panel>
+    <div role="region" aria-label="Communication settings">
+      <Panel
+        size="small"
+        header={
+          <>
+            <Icon name={COMMUNICATION_ICON_NAME} />{" "}
+            {intl.formatMessage(labels.communication)}
+          </>
+        }
+      >
+        {render_global_banner()}
+        {render_no_free_warnings()}
+        {render_no_email_new_messages()}
+      </Panel>
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences-editor.tsx b/src/packages/frontend/account/account-preferences-editor.tsx
@@ -11,5 +11,9 @@ import { EditorSettings } from "./editor-settings/editor-settings";
 export const EDITOR_ICON_NAME: IconName = "edit";
 
 export function AccountPreferencesEditor() {
-  return <EditorSettings />;
+  return (
+    <div role="region" aria-label="Editor settings">
+      <EditorSettings />
+    </div>
+  );
 }
diff --git a/src/packages/frontend/account/account-preferences-keyboard.tsx b/src/packages/frontend/account/account-preferences-keyboard.tsx
@@ -11,5 +11,9 @@ import { KeyboardSettings } from "./keyboard-settings";
 export const KEYBOARD_ICON_NAME: IconName = "keyboard";
 
 export function AccountPreferencesKeyboard() {
-  return <KeyboardSettings />;
+  return (
+    <div role="region" aria-label="Keyboard settings">
+      <KeyboardSettings />
+    </div>
+  );
 }
diff --git a/src/packages/frontend/account/account-preferences-other.tsx b/src/packages/frontend/account/account-preferences-other.tsx
@@ -15,13 +15,15 @@ export function AccountPreferencesOther() {
   const kucalc = useTypedRedux("customize", "kucalc");
 
   return (
-    <OtherSettings
-      other_settings={other_settings}
-      is_stripe_customer={
-        !!stripe_customer?.getIn(["subscriptions", "total_count"])
-      }
-      kucalc={kucalc}
-      mode="other"
-    />
+    <div role="region" aria-label="Other settings">
+      <OtherSettings
+        other_settings={other_settings}
+        is_stripe_customer={
+          !!stripe_customer?.getIn(["subscriptions", "total_count"])
+        }
+        kucalc={kucalc}
+        mode="other"
+      />
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences-profile.tsx b/src/packages/frontend/account/account-preferences-profile.tsx
@@ -36,7 +36,7 @@ export function AccountPreferencesProfile() {
   const verify_emails = useTypedRedux("customize", "verify_emails");
 
   return (
-    <>
+    <div role="region" aria-label="Profile settings">
       <AccountSettings
         account_id={account_id}
         first_name={first_name}
@@ -55,6 +55,6 @@ export function AccountPreferencesProfile() {
         unlisted={unlisted}
       />
       <ProfileSettings email_address={email_address} />
-    </>
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences-security.tsx b/src/packages/frontend/account/account-preferences-security.tsx
@@ -20,9 +20,9 @@ export function AccountPreferencesSecurity() {
   const ssh_gateway = useTypedRedux("customize", "ssh_gateway");
 
   return (
-    <>
+    <div role="region" aria-label="Security settings">
       {(ssh_gateway || kucalc === KUCALC_COCALC_COM) && <GlobalSSHKeys />}
       {!is_anonymous && <ApiKeys />}
-    </>
+    </div>
   );
 }
diff --git a/src/packages/frontend/account/account-preferences.tsx b/src/packages/frontend/account/account-preferences.tsx
@@ -30,7 +30,7 @@ export const AccountPreferences: React.FC = () => {
   const verify_emails = useTypedRedux("customize", "verify_emails");
 
   return (
-    <div>
+    <div role="region" aria-label="Account preferences">
       <TableError />
       <AccountSettings
         account_id={account_id}
diff --git a/src/packages/frontend/components/icon.tsx b/src/packages/frontend/components/icon.tsx
@@ -729,6 +729,15 @@ interface Props {
   onMouseOut?: () => void;
   onMouseEnter?: () => void;
   onMouseLeave?: () => void;
+  onKeyDown?: (event: React.KeyboardEvent) => void;
+  // ARIA attributes for accessibility
+  role?: string;
+  "aria-label"?: string;
+  "aria-expanded"?: boolean;
+  "aria-pressed"?: boolean;
+  "aria-live"?: "polite" | "assertive" | "off";
+  "aria-atomic"?: boolean;
+  tabIndex?: number;
 }
 
 const UNICODE_STYLE = {
@@ -765,7 +774,22 @@ export const Icon: React.FC<Props> = (props: Props) => {
     }
 
     return (
-      <span style={style}>
+      <span
+        style={style}
+        role={props.role}
+        aria-label={props["aria-label"]}
+        aria-expanded={props["aria-expanded"]}
+        aria-pressed={props["aria-pressed"]}
+        aria-live={props["aria-live"]}
+        aria-atomic={props["aria-atomic"]}
+        tabIndex={props.tabIndex}
+        onClick={props.onClick}
+        onKeyDown={props.onKeyDown}
+        onMouseOver={props.onMouseOver}
+        onMouseOut={props.onMouseOut}
+        onMouseEnter={props.onMouseEnter}
+        onMouseLeave={props.onMouseLeave}
+      >
         {String.fromCharCode(props.unicode!)}
       </span>
     );
@@ -780,14 +804,31 @@ export const Icon: React.FC<Props> = (props: Props) => {
     C = IconSpec[name.slice(0, name.length - 2)];
   }
   if (C != null) {
+    const ariaProps = {
+      role: props.role,
+      "aria-label": props["aria-label"],
+      "aria-expanded": props["aria-expanded"],
+      "aria-pressed": props["aria-pressed"],
+      "aria-live": props["aria-live"],
+      "aria-atomic": props["aria-atomic"],
+      tabIndex: props.tabIndex,
+      onKeyDown: props.onKeyDown,
+    };
     if (typeof C.IconFont == "string") {
       // @ts-ignore
       if (IconFont == null) {
         return <span>(IconFonts not available)</span>;
       }
-      return <IconFont type={"icon-" + C.IconFont} {...props} alt={name} />;
+      return (
+        <IconFont
+          type={"icon-" + C.IconFont}
+          {...props}
+          {...ariaProps}
+          alt={name}
+        />
+      );
     }
-    return <C {...props} alt={name} />;
+    return <C {...props} {...ariaProps} alt={name} />;
   }
 
   // this is when the icon is broken.
diff --git a/src/packages/frontend/frame-editors/frame-tree/editor.tsx b/src/packages/frontend/frame-editors/frame-tree/editor.tsx
@@ -200,7 +200,12 @@ const FrameTreeEditor: React.FC<FrameTreeEditorProps> = React.memo(
     }
 
     return (
-      <div className="smc-vfill cc-frame-tree-editor" ref={frameRootRef}>
+      <div
+        className="smc-vfill cc-frame-tree-editor"
+        ref={frameRootRef}
+        role="application"
+        aria-label={`${editor_spec.name || name} editor for ${path}`}
+      >
         {formatError && (
           <FormatError formatError={formatError} formatInput={formatInput} />
         )}
diff --git a/src/packages/frontend/frame-editors/frame-tree/frame-tree.tsx b/src/packages/frontend/frame-editors/frame-tree/frame-tree.tsx
@@ -3,6 +3,8 @@
  *  License: MS-RSL – see LICENSE.md for details
  */
 
+// cSpell:ignore subframe
+
 /*
 FrameTree -- a binary tree of editor frames.
 
diff --git a/src/packages/frontend/frame-editors/frame-tree/status-bar.tsx b/src/packages/frontend/frame-editors/frame-tree/status-bar.tsx
@@ -13,9 +13,12 @@ This is basically used now as "ephemeral messages".
 */
 
 import { CSSProperties } from "react";
+
 import { Icon, Gap } from "@cocalc/frontend/components";
 
-const STYLE = {
+type CSS = CSSProperties;
+
+const STYLE: CSS = {
   opacity: 0.85,
   position: "fixed",
   bottom: "0px",
@@ -29,7 +32,7 @@ const STYLE = {
   fontSize: "9pt",
   background: "#fff",
   boxShadow: "-2px -2px 2px #ccc",
-} as CSSProperties;
+} as const;
 
 interface Props {
   status: string;
@@ -38,11 +41,25 @@ interface Props {
 
 export default function StatusBar({ status, onClear }: Props) {
   return (
-    <div style={STYLE}>
+    <div
+      style={STYLE}
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      aria-label={`Editor status: ${status}`}
+    >
       <Icon
         name="times"
         onClick={onClear}
         style={{ float: "right", marginTop: "2.5px" }}
+        role="button"
+        tabIndex={0}
+        aria-label="Clear status message"
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            onClear();
+          }
+        }}
       />
       {status}
       <Gap />
diff --git a/src/packages/frontend/frame-editors/frame-tree/title-bar.tsx b/src/packages/frontend/frame-editors/frame-tree/title-bar.tsx
