Align tool action group semantics (#263)

Author: baixiangcpp

docs/accessibility/bf-036-bf-038-keyboard-visual-qa.md

@@ -31,7 +31,7 @@ Scope: representative navigation, discovery, tool action, upload, and output sur
 ## Automated Coverage
 
 - `tests/guards/focus-visible-guard.test.ts` prevents removing visible focus rings from app/component surfaces.
-- `tests/guards/shared-a11y-surfaces.test.ts` guards All Tools dialog focus trap/restore behavior, shared action toolbar names, and Pipeline Builder run status.
+- `tests/guards/shared-a11y-surfaces.test.ts` guards All Tools dialog focus trap/restore behavior, shared action-group names, and Pipeline Builder run status.
 - `tests/guards/a11y-mobile-baseline.test.ts` guards skip-link behavior, live toast feedback, mobile touch target baseline, and core mobile routes.
 - `tests/guards/all-tools-performance-a11y-guard.test.ts` guards disabled explanations plus long-text/mobile containment on All Tools.
 - `tests/guards/theme-contrast-token-guard.test.ts` checks light/dark foreground and muted text contrast tokens against WCAG AA.

docs/accessibility/bf-037-screen-reader-qa.md

@@ -17,7 +17,7 @@ Scope: representative dynamic tool interfaces for BF-037.
 - All Tools: search exposes the result-count status as its accessible description; filtered result counts announce through a polite live region; the mobile filter drawer has a dialog name, description, trapped focus, Escape close, and focus restoration.
 - Pipeline Builder: final output is label-associated; run-log status announces through a polite live region; the run-log table has an accessible name; run failures expose an alert.
 - External-request media flow: confirmation panel identifies the destination/purpose/data sent; preview/download actions remain disabled with accessible descriptions until explicit confirmation.
-- Shared tool actions: action groups expose a toolbar label; disabled actions use visible button names plus programmatic descriptions, without exposing tool payloads.
+- Shared tool actions: action groups expose a named group container; disabled actions use visible button names plus programmatic descriptions, without exposing tool payloads.
 - Copy, download, export, save, and share feedback: toast title/description text is mirrored into the shared polite status region so success and failure states are announced consistently.
 
 ## Automated Coverage

src/features/tool-shell/tool-action-bar.tsx

@@ -273,7 +273,7 @@ export function ToolActionBar({
     return (
         <div
             className={joinClasses("flex w-full flex-wrap items-center gap-2 sm:w-auto", className)}
-            role="toolbar"
+            role="group"
             aria-label={t.common.tool_actions}
         >
             {primaryActions.map((action) => {

tests/component/http-request-builder-page.test.tsx

@@ -126,7 +126,7 @@ describe("HttpRequestBuilderPage", () => {
 
         expect(screen.getByRole("group", { name: "Add to favorites / Remove from favorites" })).toHaveAttribute("data-tool-global-actions")
         expect(screen.getByRole("button", { name: "Add to favorites" })).toBeInTheDocument()
-        expect(screen.getByRole("toolbar", { name: "Tool actions" })).toBeInTheDocument()
+        expect(screen.getByRole("group", { name: "Tool actions" })).toBeInTheDocument()
 
         fireEvent.click(screen.getByRole("button", { name: "Add Header" }))
         fireEvent.change(screen.getAllByRole("textbox", { name: "Header name" })[1], {

tests/component/phase3-pipeline-builder-page.test.tsx

@@ -104,7 +104,7 @@ describe("phase 3 pipeline builder page", () => {
 
         expect(screen.getByRole("heading", { name: "Pipeline Builder" })).toBeInTheDocument()
         expect(screen.getByRole("heading", { name: "Build a recipe in three moves" })).toBeInTheDocument()
-        expect(screen.getByRole("toolbar", { name: "Tool actions" })).toBeInTheDocument()
+        expect(screen.getByRole("group", { name: "Tool actions" })).toBeInTheDocument()
         expect(screen.getByLabelText("Initial input")).toBeInTheDocument()
         expect(screen.getByLabelText("Final output")).toBeInTheDocument()
         expect(screen.getAllByText("Steps").length).toBeGreaterThan(0)
@@ -310,13 +310,13 @@ describe("phase 3 pipeline builder page", () => {
         expect(screen.getByRole("button", { name: "Export structure only" })).toBeInTheDocument()
     }, 10_000)
 
-    it("restores privacy dialog focus for toolbar and inspector actions", async () => {
+    it("restores privacy dialog focus for action-bar and inspector actions", async () => {
         renderWithEnglish(<PipelineBuilderPage />)
 
-        const toolbar = screen.getByRole("toolbar", { name: "Tool actions" })
-        const toolbarExport = within(toolbar).getByRole("button", { name: "Export JSON" })
-        toolbarExport.focus()
-        fireEvent.click(toolbarExport)
+        const actionGroup = screen.getByRole("group", { name: "Tool actions" })
+        const actionGroupExport = within(actionGroup).getByRole("button", { name: "Export JSON" })
+        actionGroupExport.focus()
+        fireEvent.click(actionGroupExport)
 
         const firstDialog = await screen.findByRole("dialog", { name: "Privacy preview" })
         expect(firstDialog).toHaveAccessibleDescription("Export a structure-only JSON recipe file.")
@@ -339,14 +339,14 @@ describe("phase 3 pipeline builder page", () => {
         fireEvent.keyDown(document, { key: "Escape" })
 
         await waitFor(() => expect(screen.queryByRole("dialog", { name: "Privacy preview" })).not.toBeInTheDocument())
-        await waitFor(() => expect(toolbarExport).toHaveFocus())
+        await waitFor(() => expect(actionGroupExport).toHaveFocus())
 
-        fireEvent.click(toolbarExport)
+        fireEvent.click(actionGroupExport)
         const cancelDialog = await screen.findByRole("dialog", { name: "Privacy preview" })
         fireEvent.click(within(cancelDialog).getByRole("button", { name: "Cancel" }))
 
         await waitFor(() => expect(screen.queryByRole("dialog", { name: "Privacy preview" })).not.toBeInTheDocument())
-        await waitFor(() => expect(toolbarExport).toHaveFocus())
+        await waitFor(() => expect(actionGroupExport).toHaveFocus())
 
         const inspector = screen.getByRole("complementary", { name: "Recipe inspector" })
         const inspectorExport = within(inspector).getByRole("button", { name: "Export JSON" })

tests/component/tool-action-bar.test.tsx

@@ -45,9 +45,12 @@ describe("ToolActionBar", () => {
 
         render(<ToolActionBar actions={actions} />)
 
-        const toolbar = screen.getByRole("toolbar", { name: "Tool actions" })
-        const labels = within(toolbar).getAllByRole("button").map((button) => button.textContent)
+        const actionGroup = screen.getByRole("group", { name: "Tool actions" })
+        const actionButtons = within(actionGroup).getAllByRole("button")
+        const labels = actionButtons.map((button) => button.textContent)
 
+        expect(screen.queryByRole("toolbar", { name: "Tool actions" })).not.toBeInTheDocument()
+        expect(actionButtons.filter((button) => !button.hasAttribute("disabled")).every((button) => button.tabIndex === 0)).toBe(true)
         expect(labels).toEqual(["Sample", "Clear", "Format", "Copy", "Download"])
         expect(screen.getByRole("button", { name: "Download", description: "Nothing to download." })).toHaveAttribute("title", "Download: Nothing to download.")
     })

tests/guards/shared-a11y-surfaces.test.ts

@@ -23,7 +23,8 @@ describe("shared accessibility surfaces", () => {
     it("keeps the shared tool action bar named and described", () => {
         const source = readSource("src/features/tool-shell/tool-action-bar.tsx")
 
-        expect(source).toContain("role=\"toolbar\"")
+        expect(source).toContain("role=\"group\"")
+        expect(source).not.toContain("role=\"toolbar\"")
         expect(source).toContain("aria-label={t.common.tool_actions}")
         expect(source).toContain("aria-describedby={disabledDescriptionId}")
         expect(source).toContain("aria-describedby={handoffDisabledDescriptionId}")