@stigmer/react 3.1.2 → 3.1.4

package/src/workspace/EditorTabs.tsx

@@ -4,6 +4,17 @@ import { useCallback, type KeyboardEvent, type MouseEvent } from "react";
 import { cn } from "@stigmer/theme";
 import { editorKey, type OpenEditor } from "../internal/store/index.js";
 
+/**
+ * Deterministic, space-free DOM id for a tab, built from an instance-scoped
+ * `prefix` (a `useId()` value) and the editor `key`. Shared by the tab (its
+ * `id`) and the editor body (its `aria-labelledby`) so the two associate; the
+ * key is percent-encoded because editor keys embed file paths that may contain
+ * characters (spaces) illegal in a space-separated IDREF.
+ */
+export function editorTabDomId(prefix: string, key: string): string {
+  return `${prefix}${encodeURIComponent(key)}`;
+}
+
 /** Props for {@link EditorTabs}. */
 export interface EditorTabsProps {
   /** Open editors in tab order. */
@@ -16,6 +27,14 @@ export interface EditorTabsProps {
   readonly onPin: (entryId: string, path: string) => void;
   /** Close an editor (close button or middle click). */
   readonly onClose: (entryId: string, path: string) => void;
+  /**
+   * DOM id of the editor body (`role="tabpanel"`). When provided together with
+   * {@link tabIdPrefix}, each tab gets a stable `id` and `aria-controls` linking
+   * it to that panel. Optional so the strip degrades gracefully without a panel.
+   */
+  readonly panelId?: string;
+  /** Instance-scoped prefix for per-tab ids (see {@link editorTabDomId}). */
+  readonly tabIdPrefix?: string;
   /** Additional CSS classes for the root element. */
   readonly className?: string;
 }
@@ -28,8 +47,10 @@ export interface EditorTabsProps {
  *
  * A `role="tablist"` of `role="tab"` items; the matching `tabpanel` is the
  * editor body rendered by the surface. Arrow keys move focus between tabs and
- * activate; the per-tab close button is a nested control. All visual properties
- * flow through `--stgm-*` tokens (DD-005).
+ * activate; Delete/Backspace closes the focused tab. The visual close "X" is a
+ * presentational (`aria-hidden`) mouse affordance — assistive tech closes via
+ * the keyboard, so the X is not a nested interactive control (WCAG 4.1.2). All
+ * visual properties flow through `--stgm-*` tokens (DD-005).
  */
 export function EditorTabs({
   editors,
@@ -37,6 +58,8 @@ export function EditorTabs({
   onActivate,
   onPin,
   onClose,
+  panelId,
+  tabIdPrefix,
   className,
 }: EditorTabsProps) {
   const move = useCallback(
@@ -94,7 +117,9 @@ export function EditorTabs({
           <div
             key={key}
             role="tab"
+            id={tabIdPrefix ? editorTabDomId(tabIdPrefix, key) : undefined}
             aria-selected={isActive}
+            aria-controls={panelId}
             tabIndex={isActive ? 0 : -1}
             title={editor.path}
             onClick={() => onActivate(editor.entryId, editor.path)}
@@ -112,22 +137,26 @@ export function EditorTabs({
             <span className={cn("truncate", editor.preview && "italic")}>
               {basename}
             </span>
-            <button
-              type="button"
+            {/* The visual close "X" is a presentational mouse affordance, NOT a
+                nested interactive control: a `<button>` inside `role="tab"` would
+                violate WCAG 4.1.2 (axe `nested-interactive`). Assistive tech and
+                keyboard users close the focused tab via Delete/Backspace (handled
+                above), so `aria-hidden` here removes the redundant nested control
+                without losing the close action for anyone. */}
+            <span
+              aria-hidden="true"
+              title={`Close ${basename}`}
               onClick={(e) => {
                 e.stopPropagation();
                 onClose(editor.entryId, editor.path);
               }}
-              aria-label={`Close ${basename}`}
-              tabIndex={-1}
               className={cn(
-                "shrink-0 rounded p-0.5 text-muted-foreground transition-opacity hover:bg-accent-hover hover:text-foreground",
-                "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+                "shrink-0 cursor-pointer rounded p-0.5 text-muted-foreground transition-opacity hover:bg-accent-hover hover:text-foreground",
                 isActive ? "opacity-100" : "opacity-0 group-hover:opacity-100",
               )}
             >
               <CloseIcon />
-            </button>
+            </span>
           </div>
         );
       })}

package/src/workspace/ExplorerTree.tsx

@@ -101,7 +101,10 @@ function ExplorerRoot({
           )}
           title={entry.type === "local" ? entry.localPath : entry.gitUrl}
         >
-          <span className="text-[10px] text-muted-foreground-subtle">
+          <span
+            aria-hidden="true"
+            className="text-[10px] text-muted-foreground-subtle"
+          >
             {expanded ? "▼" : "▶"}
           </span>
           <span className="truncate">{entry.name}</span>
@@ -167,6 +170,10 @@ function ExplorerRootBody({
   if (isLoading) {
     return (
       <div
+        // role="status" both announces the loading state to assistive tech and
+        // makes aria-label permitted here (a role-less generic div cannot carry
+        // an accessible name — axe `aria-prohibited-attr`).
+        role="status"
         className="space-y-1.5 px-2 py-2"
         aria-busy="true"
         aria-label={`Loading files for ${entryName}`}
@@ -190,7 +197,7 @@ function ExplorerRootBody({
         <button
           type="button"
           onClick={onRetry}
-          className="ml-2 underline transition-colors hover:text-destructive"
+          className="ml-2 rounded-sm underline transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Retry
         </button>
@@ -226,8 +233,7 @@ function ExplorerRootBody({
       </nav>
       {truncated && (
         <p className="px-3 py-1.5 text-[0.65rem] text-muted-foreground">
-          Showing a partial listing — this repository has too many files to load
-          in full.
+          Showing a partial listing — too many files to load in full.
         </p>
       )}
     </>

package/src/workspace/FileViewer.tsx

@@ -5,6 +5,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useRef,
   useState,
   type KeyboardEvent,
 } from "react";
@@ -194,7 +195,10 @@ export const FileViewer = forwardRef<FileViewerHandle, FileViewerProps>(
     <div
       role="region"
       aria-label="File viewer"
-      className={cn("flex h-full flex-col", className)}
+      // Focusable (programmatically / on click) so the Escape-to-close handler
+      // fires even when the read-only body holds no natively focusable element.
+      tabIndex={-1}
+      className={cn("flex h-full flex-col focus:outline-none", className)}
       onKeyDown={handleKeyDown}
     >
       {showHeader && (
@@ -260,17 +264,26 @@ function ViewerModeToggle({
     { value: "file", label: "File" },
   ];
 
+  // Selection follows focus, matching ActivityRail / SearchModeToggle.
+  const buttonRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  const selectValue = useCallback(
+    (next: "diff" | "file") => {
+      onChange(next);
+      buttonRefs.current[next === "diff" ? 0 : 1]?.focus();
+    },
+    [onChange],
+  );
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLButtonElement>) => {
       if (e.key === "ArrowRight" || e.key === "ArrowDown") {
         e.preventDefault();
-        onChange("file");
+        selectValue("file");
       } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
         e.preventDefault();
-        onChange("diff");
+        selectValue("diff");
       }
     },
-    [onChange],
+    [selectValue],
   );
 
   return (
@@ -280,11 +293,14 @@ function ViewerModeToggle({
         aria-label="File view"
         className="inline-flex rounded-md bg-muted p-0.5"
       >
-        {options.map((option) => {
+        {options.map((option, index) => {
           const isSelected = value === option.value;
           return (
             <button
               key={option.value}
+              ref={(el) => {
+                buttonRefs.current[index] = el;
+              }}
               type="button"
               role="radio"
               aria-checked={isSelected}
@@ -340,7 +356,12 @@ function FileViewerBody({
 
   if (isLoading) {
     return (
-      <div className="space-y-2 p-4" aria-busy="true" aria-label="Loading file">
+      <div
+        role="status"
+        className="space-y-2 p-4"
+        aria-busy="true"
+        aria-label="Loading file"
+      >
         {SKELETON_LINE_WIDTHS.map((width, i) => (
           <div
             key={i}

package/src/workspace/WorkspaceContentSearch.tsx

@@ -161,8 +161,28 @@ export function WorkspaceContentSearch({
   const belowMinLength = trimmed.length > 0 && trimmed.length < MIN_QUERY_LENGTH;
   const showEntryHeaders = groups.length > 1;
 
+  // Screen-reader-only summary in a persistent polite live region: status swaps
+  // (searching → results/none) happen across separate unmounting branches, so a
+  // stable region is what actually gets announced. Terse by design.
+  const statusMessage = isUnsupported
+    ? ""
+    : trimmed.length === 0
+      ? ""
+      : belowMinLength
+        ? `Type at least ${MIN_QUERY_LENGTH} characters to search.`
+        : isLoading
+          ? "Searching file contents…"
+          : groups.length === 0
+            ? `No files containing ${trimmed}.`
+            : totalMatches > flatResults.length
+              ? `Showing the first ${flatResults.length} of ${totalMatches} matches.`
+              : `${totalMatches} ${totalMatches === 1 ? "match" : "matches"}.`;
+
   return (
     <div className={cn("flex h-full flex-col", className)}>
+      <div role="status" aria-live="polite" className="sr-only">
+        {statusMessage}
+      </div>
       <div className="flex items-center gap-1.5 border-b border-border px-2 py-1.5">
         <SearchIcon />
         <input
@@ -336,27 +356,31 @@ function LineRow({
   readonly isOpen: boolean;
   readonly onOpen: () => void;
 }) {
+  // The `role="option"` IS the interactive leaf of the listbox (keyboard
+  // activation flows through the combobox input's Enter handler +
+  // aria-activedescendant). It must not nest another interactive control — a
+  // button inside would violate WCAG 4.1.2 (axe `nested-interactive`). So the
+  // click handler and row styling live on the option itself.
   return (
-    <li id={id} role="option" aria-selected={isFocused}>
-      <button
-        type="button"
-        onClick={onOpen}
-        tabIndex={-1}
-        aria-current={isOpen ? "true" : undefined}
-        className={cn(
-          "flex w-full items-baseline gap-2 py-0.5 pl-6 pr-3 text-left text-xs transition-colors",
-          isFocused && "bg-muted",
-          isOpen && "bg-muted",
-          !isFocused && !isOpen && "hover:bg-muted",
-        )}
-      >
-        <span className="w-8 shrink-0 text-right font-mono text-[0.65rem] tabular-nums text-muted-foreground-subtle">
-          {match.line}
-        </span>
-        <span className="min-w-0 flex-1 truncate font-mono text-muted-foreground">
-          <HighlightedPreview text={match.preview} query={query} />
-        </span>
-      </button>
+    <li
+      id={id}
+      role="option"
+      aria-selected={isFocused}
+      aria-current={isOpen ? "true" : undefined}
+      onClick={onOpen}
+      className={cn(
+        "flex cursor-pointer items-baseline gap-2 py-0.5 pl-6 pr-3 text-xs transition-colors",
+        isFocused && "bg-muted",
+        isOpen && "bg-muted",
+        !isFocused && !isOpen && "hover:bg-muted",
+      )}
+    >
+      <span className="w-8 shrink-0 text-right font-mono text-[0.65rem] tabular-nums text-muted-foreground-subtle">
+        {match.line}
+      </span>
+      <span className="min-w-0 flex-1 truncate font-mono text-muted-foreground">
+        <HighlightedPreview text={match.preview} query={query} />
+      </span>
     </li>
   );
 }

package/src/workspace/WorkspaceEditor.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState, useCallback, useEffect, type KeyboardEvent } from "react";
+import { cn } from "@stigmer/theme";
 import type { UseWorkspaceEntriesReturn } from "./useWorkspaceEntries.js";
 import type { UseGitHubConnectionReturn } from "../github/useGitHubConnection.js";
 import { GitHubRepoPicker } from "../github/GitHubRepoPicker.js";
@@ -136,11 +137,11 @@ export function WorkspaceEditor({
 
   if (activePanel === "github" && enableGitHub) {
     return (
-      <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+      <div className={cn("space-y-2", className)}>
         <button
           type="button"
           onClick={goBack}
-          className="inline-flex items-center gap-1 text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+          className="inline-flex items-center gap-1 rounded-sm text-[0.65rem] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           <ChevronLeftIcon />
           Back
@@ -180,7 +181,7 @@ export function WorkspaceEditor({
   // ---------------------------------------------------------------------------
 
   return (
-    <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+    <div className={cn("space-y-2", className)}>
       {/* Entry list */}
       {workspace.entries.length > 0 && (
         <div className="relative">
@@ -202,10 +203,10 @@ export function WorkspaceEditor({
                   </span>
                 )}
                 <span
-                  className={[
+                  className={cn(
                     "min-w-0 flex-1 truncate text-foreground",
-                    entry.type === "local" ? "[direction:rtl] text-left" : "",
-                  ].join(" ")}
+                    entry.type === "local" && "[direction:rtl] text-left",
+                  )}
                   title={entry.name}
                 >
                   <bdi>{entry.name}</bdi>
@@ -214,7 +215,7 @@ export function WorkspaceEditor({
                   type="button"
                   onClick={() => workspace.remove(entry.id)}
                   disabled={disabled}
-                  className="shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
+                  className="shrink-0 rounded-sm text-muted-foreground transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none"
                   aria-label={`Remove ${entry.name}`}
                 >
                   <XIcon />
@@ -237,7 +238,7 @@ export function WorkspaceEditor({
               if (path) workspace.addLocalPath(path);
             }}
             disabled={disabled}
-            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
           >
             <FolderIcon />
             <span className="flex-1 text-left">Browse Folder</span>
@@ -248,7 +249,7 @@ export function WorkspaceEditor({
             type="button"
             onClick={() => setActivePanel("github")}
             disabled={disabled}
-            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
           >
             <GitHubIcon />
             <span className="flex-1 text-left">Connect GitHub</span>
@@ -307,14 +308,14 @@ function GitHubPanel({
               <button
                 type="button"
                 onClick={() => connection.connect(redirectUri, { popup: true })}
-                className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+                className="rounded-md px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 Try again
               </button>
               <button
                 type="button"
                 onClick={() => connection.connect(redirectUri)}
-                className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background hover:bg-foreground-hover transition-colors"
+                className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background transition-colors hover:bg-foreground-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 <GitHubIcon />
                 <span>Continue with redirect</span>
@@ -325,7 +326,7 @@ function GitHubPanel({
           <button
             type="button"
             onClick={() => connection.connect(redirectUri, { popup: true })}
-            className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background hover:bg-foreground-hover transition-colors"
+            className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background transition-colors hover:bg-foreground-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           >
             <GitHubIcon />
             <span>Connect GitHub</span>
@@ -353,7 +354,7 @@ function GitHubPanel({
         <button
           type="button"
           onClick={connection.disconnect}
-          className="text-[0.6rem] text-muted-foreground hover:text-destructive transition-colors"
+          className="rounded-sm text-[0.6rem] text-muted-foreground transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Disconnect
         </button>
@@ -392,6 +393,7 @@ function ManualGitPanel({
     <div className="space-y-2">
       <input
         type="url"
+        aria-label="Git repository URL"
         placeholder="https://github.com/org/repo.git"
         value={url}
         onChange={(e) => onUrlChange(e.target.value)}
@@ -401,6 +403,7 @@ function ManualGitPanel({
       />
       <input
         type="text"
+        aria-label="Branch (optional)"
         placeholder="Branch (optional)"
         value={branch}
         onChange={(e) => onBranchChange(e.target.value)}
@@ -411,7 +414,7 @@ function ManualGitPanel({
         <button
           type="button"
           onClick={onCancel}
-          className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+          className="rounded-md px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Cancel
         </button>
@@ -419,7 +422,7 @@ function ManualGitPanel({
           type="button"
           onClick={onAdd}
           disabled={!url.trim()}
-          className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground hover:bg-primary-hover transition-colors disabled:opacity-40"
+          className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground transition-colors hover:bg-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-40"
         >
           Add
         </button>
@@ -453,7 +456,7 @@ function GitHubConnectingState({ onCancel }: { onCancel: () => void }) {
       <button
         type="button"
         onClick={onCancel}
-        className="text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+        className="rounded-sm text-[0.65rem] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
       >
         Cancel
       </button>

package/src/workspace/WorkspaceFileSearch.tsx

@@ -132,8 +132,27 @@ export function WorkspaceFileSearch({
   const trimmed = query.trim();
   const showGroupHeaders = groups.length > 1;
 
+  // A concise, screen-reader-only summary of the current result state. It lives
+  // in a persistent polite live region (below) so status changes are announced
+  // even as the visible states — which live in separate, unmounting branches —
+  // swap. Deliberately terse: never the result list itself, only its shape.
+  const statusMessage = isUnsupported
+    ? ""
+    : trimmed.length === 0
+      ? ""
+      : isLoading && totalMatches === 0 && groups.length === 0
+        ? "Searching files…"
+        : groups.length === 0
+          ? `No files matching ${trimmed}.`
+          : totalMatches > flatResults.length
+            ? `Showing the first ${flatResults.length} of ${totalMatches} matching files.`
+            : `${flatResults.length} matching ${flatResults.length === 1 ? "file" : "files"}.`;
+
   return (
     <div className={cn("flex h-full flex-col", className)}>
+      <div role="status" aria-live="polite" className="sr-only">
+        {statusMessage}
+      </div>
       <div className="flex items-center gap-1.5 border-b border-border px-2 py-1.5">
         <SearchIcon />
         <input
@@ -264,7 +283,7 @@ function renderRows({
     if (group.truncated) {
       rows.push(
         <GroupNotice key={`t:${group.entry.id}`}>
-          Partial listing — this repository has too many files to search in full.
+          Partial listing — too many files to search in full.
         </GroupNotice>,
       );
     }
@@ -299,39 +318,43 @@ function ResultRow({
   const basename = match.path.slice(lastSlash + 1);
   const dir = lastSlash >= 0 ? match.path.slice(0, lastSlash) : "";
 
+  // The `role="option"` IS the interactive leaf of the listbox (keyboard
+  // activation flows through the combobox input's Enter handler +
+  // aria-activedescendant). It must not nest another interactive control — a
+  // button inside would violate WCAG 4.1.2 (axe `nested-interactive`). So the
+  // click handler and row styling live on the option itself.
   return (
-    <li id={id} role="option" aria-selected={isFocused}>
-      <button
-        type="button"
-        onClick={onOpen}
-        tabIndex={-1}
-        aria-current={isOpen ? "true" : undefined}
-        className={cn(
-          "flex w-full items-baseline gap-1.5 px-3 py-1 text-left text-xs transition-colors",
-          isFocused && "bg-muted",
-          isOpen && "bg-muted font-medium text-foreground",
-          !isFocused && !isOpen && "hover:bg-muted",
-        )}
-      >
-        <span className="truncate text-foreground">
+    <li
+      id={id}
+      role="option"
+      aria-selected={isFocused}
+      aria-current={isOpen ? "true" : undefined}
+      onClick={onOpen}
+      className={cn(
+        "flex cursor-pointer items-baseline gap-1.5 px-3 py-1 text-xs transition-colors",
+        isFocused && "bg-muted",
+        isOpen && "bg-muted font-medium text-foreground",
+        !isFocused && !isOpen && "hover:bg-muted",
+      )}
+    >
+      <span className="truncate text-foreground">
+        <HighlightedPath
+          text={basename}
+          offset={lastSlash + 1}
+          matchStart={match.matchStart}
+          matchEnd={match.matchEnd}
+        />
+      </span>
+      {dir && (
+        <span className="truncate text-[0.65rem] text-muted-foreground">
           <HighlightedPath
-            text={basename}
-            offset={lastSlash + 1}
+            text={dir}
+            offset={0}
             matchStart={match.matchStart}
             matchEnd={match.matchEnd}
           />
         </span>
-        {dir && (
-          <span className="truncate text-[0.65rem] text-muted-foreground">
-            <HighlightedPath
-              text={dir}
-              offset={0}
-              matchStart={match.matchStart}
-              matchEnd={match.matchEnd}
-            />
-          </span>
-        )}
-      </button>
+      )}
     </li>
   );
 }