From 97ee765c438d72a31c9c0e3356b8e0f430bd3c7b Mon Sep 17 00:00:00 2001
From: Adam Wright <adam.j.wright82@gmail.com>
Date: Wed, 16 Sep 2026 16:15:41 +0000
Subject: [PATCH 1/2] fix(viewport): let the Species and Interactors controls
 be used without a mouse

Closes #211, found while reviewing #208.

Both were plain divs with a click handler -- measured on beta:
`{ role: null, tabindex: null, focusable: false }`. Neither could be
focused or activated from the keyboard, and neither was announced as
anything at all. They are the way in to species filtering and to the
interactor overlay, so that is the whole feature closed to anyone not
using a mouse.

Each now carries the role, the tab stop and the key handling that make it
behave as the button it already looks like, plus a label and an
aria-expanded that follows the panel. They keep their markup rather than
becoming <button> elements: these carry layout the surrounding flex rules
depend on, and a button would bring its own.

Space calls preventDefault, because the default action for Space on a
focused element is to scroll the page.

The e2e case drives them the way someone without a mouse does -- focus,
then a key -- rather than checking the attributes are present. The
attributes are the mechanism; reaching the panel is the thing. Shown red
against the old markup at the first assertion: the control would not take
focus.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 e2e/header-controls.spec.ts                   | 75 +++++++++++++++++++
 .../src/app/viewport/viewport.component.html  | 26 ++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 e2e/header-controls.spec.ts

diff --git a/e2e/header-controls.spec.ts b/e2e/header-controls.spec.ts
new file mode 100644
index 00000000..008ef887
--- /dev/null
+++ b/e2e/header-controls.spec.ts
@@ -0,0 +1,75 @@
+/**
+ * The Species and Interactors controls can be used without a mouse.
+ *
+ * Both were plain `<div>`s with a click handler — measured on beta 2026-09-16:
+ * `{ role: null, tabindex: null, focusable: false }`. So neither could be
+ * focused or activated from the keyboard, and neither was announced as anything
+ * at all. Issue #211, found while reviewing the rename in #208.
+ *
+ * Asserted by driving them the way someone without a mouse does — focus, then a
+ * key — rather than by checking the attributes are present. The attributes are
+ * the mechanism; reaching the panel is the thing.
+ */
+import { test, expect, type Page } from '@playwright/test';
+
+const PATHWAY = 'R-HSA-1368108';
+const BOOT_TIMEOUT = 90_000;
+
+/** Whether the interactors panel is actually on screen. */
+const panelOpen = (page: Page) =>
+  page.evaluate(() => {
+    const panel = document.querySelector('cr-interactors') as HTMLElement | null;
+    return !!panel && panel.offsetParent !== null && panel.getBoundingClientRect().height > 0;
+  });
+
+test.describe('The header controls', () => {
+  test.describe.configure({ timeout: 4 * 60 * 1000 });
+
+  test('open from the keyboard, and say what they are', async ({ page }) => {
+    await page.goto(`/PathwayBrowser/${PATHWAY}`, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('#cytoscape canvas', { timeout: BOOT_TIMEOUT });
+    await page.waitForTimeout(4000);
+
+    expect(await panelOpen(page), 'closed to begin with').toBe(false);
+
+    const interactors = page.locator('.species-interactor-container .interactor');
+    await interactors.focus();
+    expect(
+      await page.evaluate(() => document.activeElement?.classList.contains('interactor')),
+      'the control takes focus'
+    ).toBe(true);
+
+    await page.keyboard.press('Enter');
+    await expect.poll(() => panelOpen(page), { timeout: 15_000 }).toBe(true);
+
+    await page.keyboard.press('Enter');
+    await expect.poll(() => panelOpen(page), { timeout: 15_000 }).toBe(false);
+
+    // Space activates too, and must not scroll the page while doing it -- the
+    // default action for Space on a focused element.
+    await page.keyboard.press(' ');
+    await expect.poll(() => panelOpen(page), { timeout: 15_000 }).toBe(true);
+    expect(await page.evaluate(() => window.scrollY), 'without scrolling the page').toBe(0);
+
+    // What a screen reader is told.
+    const semantics = await page.evaluate(() => {
+      const el = document.querySelector('.species-interactor-container .interactor');
+      const species = document.querySelector('.species-interactor-container .species');
+      return {
+        role: el?.getAttribute('role'),
+        label: el?.getAttribute('aria-label'),
+        expanded: el?.getAttribute('aria-expanded'),
+        speciesRole: species?.getAttribute('role'),
+        speciesTabindex: species?.getAttribute('tabindex'),
+      };
+    });
+    expect(semantics.role).toBe('button');
+    expect(semantics.label).toBeTruthy();
+    expect(semantics.expanded, 'and its state').toBe('true');
+
+    // Species is the same pattern and the same problem; a reader tabbing through
+    // the header should meet both or neither.
+    expect(semantics.speciesRole).toBe('button');
+    expect(semantics.speciesTabindex).toBe('0');
+  });
+});
diff --git a/projects/pathway-browser/src/app/viewport/viewport.component.html b/projects/pathway-browser/src/app/viewport/viewport.component.html
index 76f28adf..c1a9619f 100644
--- a/projects/pathway-browser/src/app/viewport/viewport.component.html
+++ b/projects/pathway-browser/src/app/viewport/viewport.component.html
@@ -15,7 +15,25 @@
         <!--        <div class="sidebar">-->
 
         <div class="species-interactor-container">
-          <div class="species" (click)="toggleVisibility('species')" [ngClass]="{ selected: visibility.species }">
+          <!--
+            A div with a click handler was unreachable without a mouse: no role,
+            no tabindex, nothing announced. Given the two attributes and the key
+            handler that make it behave as the button it already looks like,
+            rather than being rewritten as one -- these carry layout the
+            surrounding flex rules depend on, and a <button> would bring its own
+            (#211).
+          -->
+          <div
+            class="species"
+            role="button"
+            tabindex="0"
+            [attr.aria-expanded]="visibility.species"
+            aria-label="Choose a species"
+            (click)="toggleVisibility('species')"
+            (keydown.enter)="toggleVisibility('species')"
+            (keydown.space)="toggleVisibility('species'); $event.preventDefault()"
+            [ngClass]="{ selected: visibility.species }"
+          >
             <mat-icon class="custom-icon" svgIcon="species"></mat-icon>
             <div class="species-content">
               <span>Species</span>
@@ -26,7 +44,13 @@
           @if (!isCurator) {
             <div
               class="interactor"
+              role="button"
+              tabindex="0"
+              [attr.aria-expanded]="visibility.interactor"
+              aria-label="Choose an interactor overlay"
               (click)="toggleVisibility('interactor')"
+              (keydown.enter)="toggleVisibility('interactor')"
+              (keydown.space)="toggleVisibility('interactor'); $event.preventDefault()"
               [ngClass]="{ selected: visibility.interactor }"
             >
               <mat-icon class="custom-icon" svgIcon="overlay"></mat-icon>

From 8d37426a3698df315f847eb0ffa2792cb0a1f5e5 Mon Sep 17 00:00:00 2001
From: Adam Wright <adam.j.wright82@gmail.com>
Date: Wed, 16 Sep 2026 16:41:46 +0000
Subject: [PATCH 2/2] fix(viewport): close the header panels with Escape, and
 give focus back

Found reviewing this PR before it merged.

Opening a panel with a key worked; getting out of one did not. Escape did
nothing, so the only way back was shift-tabbing to the control and
pressing it again -- a trap of a mild kind, because every other disclosure
on the page closes this way and a reader will try it.

Worse, closing from inside dropped focus to <body>, measured. A reader who
closed the panel had lost their place on the page entirely and had to tab
from the top.

Escape now closes either panel, from the control or from inside it, and
focus goes back to the control that opened it.

Both controls also gained aria-controls. Saying a thing is expanded
without saying what it expands is half an answer.

Tab order was checked and left alone: it already moves straight from the
control into the panel's buttons.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 e2e/header-controls.spec.ts                   | 36 +++++++++++++++++++
 .../src/app/viewport/viewport.component.html  | 24 +++++++++++--
 .../src/app/viewport/viewport.component.ts    | 29 +++++++++++++++
 3 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/e2e/header-controls.spec.ts b/e2e/header-controls.spec.ts
index 008ef887..954dacb7 100644
--- a/e2e/header-controls.spec.ts
+++ b/e2e/header-controls.spec.ts
@@ -72,4 +72,40 @@ test.describe('The header controls', () => {
     expect(semantics.speciesRole).toBe('button');
     expect(semantics.speciesTabindex).toBe('0');
   });
+
+  test('close on Escape, and give focus back', async ({ page }) => {
+    await page.goto(`/PathwayBrowser/${PATHWAY}`, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('#cytoscape canvas', { timeout: BOOT_TIMEOUT });
+    await page.waitForTimeout(4000);
+
+    await page.locator('.species-interactor-container .interactor').focus();
+    await page.keyboard.press('Enter');
+    await expect.poll(() => panelOpen(page), { timeout: 15_000 }).toBe(true);
+
+    // Into the panel, which is where a reader will be when they want out of it.
+    await page.keyboard.press('Tab');
+    expect(
+      await page.evaluate(() => !!document.activeElement?.closest('cr-interactors')),
+      'tab moves into the panel'
+    ).toBe(true);
+
+    await page.keyboard.press('Escape');
+    await expect.poll(() => panelOpen(page), { timeout: 15_000 }).toBe(false);
+
+    // And the reader still has their place. Without this focus falls to <body>,
+    // so closing the panel costs them the whole page.
+    expect(
+      await page.evaluate(() => document.activeElement?.classList.contains('interactor')),
+      'focus returns to the control that opened it'
+    ).toBe(true);
+
+    // It says what it controls, not just that it is expanded.
+    expect(
+      await page.evaluate(() =>
+        document
+          .querySelector('.species-interactor-container .interactor')
+          ?.getAttribute('aria-controls')
+      )
+    ).toBeTruthy();
+  });
 });
diff --git a/projects/pathway-browser/src/app/viewport/viewport.component.html b/projects/pathway-browser/src/app/viewport/viewport.component.html
index c1a9619f..bc1ec99e 100644
--- a/projects/pathway-browser/src/app/viewport/viewport.component.html
+++ b/projects/pathway-browser/src/app/viewport/viewport.component.html
@@ -24,14 +24,17 @@
             (#211).
           -->
           <div
+            #speciesControl
             class="species"
             role="button"
             tabindex="0"
             [attr.aria-expanded]="visibility.species"
+            aria-controls="species-panel"
             aria-label="Choose a species"
             (click)="toggleVisibility('species')"
             (keydown.enter)="toggleVisibility('species')"
             (keydown.space)="toggleVisibility('species'); $event.preventDefault()"
+            (keydown.escape)="closePanels()"
             [ngClass]="{ selected: visibility.species }"
           >
             <mat-icon class="custom-icon" svgIcon="species"></mat-icon>
@@ -43,14 +46,17 @@
           </div>
           @if (!isCurator) {
             <div
+              #interactorControl
               class="interactor"
               role="button"
               tabindex="0"
               [attr.aria-expanded]="visibility.interactor"
+              aria-controls="interactor-panel"
               aria-label="Choose an interactor overlay"
               (click)="toggleVisibility('interactor')"
               (keydown.enter)="toggleVisibility('interactor')"
               (keydown.space)="toggleVisibility('interactor'); $event.preventDefault()"
+              (keydown.escape)="closePanels()"
               [ngClass]="{ selected: visibility.interactor }"
             >
               <mat-icon class="custom-icon" svgIcon="overlay"></mat-icon>
@@ -72,11 +78,25 @@
           }
         </div>
 
-        <div [style.display]="visibility.species ? 'block' : 'none'">
+        <!--
+          Escape closes it, from anywhere inside. A panel that opens with a key
+          and can only be closed by shift-tabbing back to the control and
+          pressing it again is a trap of a mild kind -- every other disclosure on
+          the page closes this way, and a reader will try it.
+        -->
+        <div
+          id="species-panel"
+          [style.display]="visibility.species ? 'block' : 'none'"
+          (keydown.escape)="closePanels()"
+        >
           <cr-species [(pathwayId)]="pathwayId" [visibility]="visibility"></cr-species>
         </div>
 
-        <div [style.display]="visibility.interactor ? 'block' : 'none'">
+        <div
+          id="interactor-panel"
+          [style.display]="visibility.interactor ? 'block' : 'none'"
+          (keydown.escape)="closePanels()"
+        >
           <cr-interactors
             #interactors
             [cy]="diagram()?.cy"
diff --git a/projects/pathway-browser/src/app/viewport/viewport.component.ts b/projects/pathway-browser/src/app/viewport/viewport.component.ts
index 0de4e2dc..3c160533 100644
--- a/projects/pathway-browser/src/app/viewport/viewport.component.ts
+++ b/projects/pathway-browser/src/app/viewport/viewport.component.ts
@@ -227,6 +227,10 @@ export class ViewportComponent implements AfterViewInit {
 
   analysisLoading = computed(() => this.exampleAnalysis.isLoading() || this.analysis.isLoading());
 
+  /** The two header controls, so focus can be put back where it came from. */
+  readonly speciesControl = viewChild<ElementRef<HTMLElement>>('speciesControl');
+  readonly interactorControl = viewChild<ElementRef<HTMLElement>>('interactorControl');
+
   visibility = {
     species: false,
     interactor: false,
@@ -280,6 +284,31 @@ export class ViewportComponent implements AfterViewInit {
     }, 200);
   }
 
+  /**
+   * Put both panels away.
+   *
+   * Escape, from the control or from inside the panel. One that opens with a key
+   * and closes only by shift-tabbing back to the control is a trap of a mild
+   * kind: every other disclosure on the page closes this way, so a reader will
+   * try it and be surprised when nothing happens.
+   */
+  closePanels() {
+    // Which one was open, before it is not.
+    const control = this.visibility.species
+      ? this.speciesControl()
+      : this.visibility.interactor
+        ? this.interactorControl()
+        : undefined;
+
+    this.visibility.species = false;
+    this.visibility.interactor = false;
+
+    // Focus goes back to the control that opened it. Without this it falls to
+    // <body> -- measured -- and a reader who closed the panel from inside has
+    // lost their place entirely and must tab from the top of the page.
+    control?.nativeElement.focus();
+  }
+
   toggleVisibility(type: string) {
     if (type === 'species') {
       this.visibility.species = !this.visibility.species;