fix(tabs): default keyboard-activation to automatic, matching React Spectrum (#6476)

<swc-tabs> inherited keyboard-activation="manual" as its default from
1st-gen sp-tabs' auto=false, not from a deliberate accessibility decision.
React Spectrum/React Aria Tabs defaults to automatic activation, and
swc-tab-panel content is always present in the light DOM (not lazily
mounted), which is the condition the WAI-ARIA APG recommends for
automatic activation. Flip the default to automatic and document manual
as consumer guidance for expensive/lazy-loaded panels instead.

Co-authored-by: Rajdeep Chandra <rajdeepc@adobe.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Patrick Fulton <360251+pfulton@users.noreply.github.com>

Author: 4 people

.changeset/fix-tabs-keyboard-activation-default.md

@@ -0,0 +1,7 @@
+---
+'@adobe/spectrum-wc': minor
+---
+
+**fix(tabs):** Changed the default `keyboard-activation` on `<swc-tabs>` from `manual` to `automatic`, aligning with React Spectrum/React Aria `Tabs`.
+
+`swc-tab-panel` content is always present in the light DOM (not lazily mounted), which is the condition the WAI-ARIA APG recommends for automatic activation. Consumers relying on the previous implicit `manual` default (inherited from 1st-gen `sp-tabs`' `auto = false`) should add `keyboard-activation="manual"` explicitly, particularly if their own panel content is expensive to render or lazy-loaded.

2nd-gen/packages/core/components/tabs/Tabs.base.ts

@@ -71,8 +71,9 @@ export abstract class TabsBase extends SpectrumElement {
   static readonly VALID_DENSITIES: readonly TabDensity[] = TAB_DENSITIES;
 
   /**
-   * Whether selection follows keyboard focus (`automatic`) or the user
-   * must press Enter or Space to activate (`manual`, default).
+   * Whether selection follows keyboard focus (`automatic`, default) or the
+   * user must press Enter or Space to activate (`manual`). Prefer `manual`
+   * when tab panels are expensive to render or not fully present in the DOM.
    *
    * @see https://w3c.github.io/aria-practices/#kbd_selection_follows_focus
    */

2nd-gen/packages/core/components/tabs/Tabs.types.ts

@@ -26,15 +26,17 @@ export const TABS_DEFAULT_DIRECTION =
 /**
  * How keyboard focus interacts with selection (Spectrum Design / S2 naming).
  *
- * - **`manual`**: Arrow keys move focus; Enter or Space activates (default).
- * - **`automatic`**: Selection follows focus as the user arrows between tabs.
+ * - **`automatic`**: Selection follows focus as the user arrows between tabs
+ *   (default, matches React Spectrum/React Aria `Tabs`).
+ * - **`manual`**: Arrow keys move focus; Enter or Space activates. Prefer this
+ *   for tab panels that are expensive to render or not fully present in the DOM.
  */
 export const KEYBOARD_ACTIVATIONS = ['manual', 'automatic'] as const;
 
 export type KeyboardActivation = (typeof KEYBOARD_ACTIVATIONS)[number];
 
 export const KEYBOARD_ACTIVATION_DEFAULT =
-  'manual' as const satisfies KeyboardActivation;
+  'automatic' as const satisfies KeyboardActivation;
 
 /**
  * Tab list density (Spectrum Design `density` naming).

2nd-gen/packages/swc/components/tabs/migration-guide.mdx

@@ -49,14 +49,14 @@ import '@adobe/spectrum-wc/components/tabs/swc-tab-panel.js';
 
 | Addition                        | Notes                                                             |
 | ------------------------------- | ----------------------------------------------------------------- |
-| `keyboard-activation` attribute | `'manual'` (default) or `'automatic'` — replaces boolean `auto`   |
+| `keyboard-activation` attribute | `'automatic'` (default) or `'manual'` — replaces boolean `auto`   |
 | `density` attribute             | `'regular'` (default) or `'compact'` — replaces boolean `compact` |
 
 ### Removed in Spectrum 2
 
 | Removed                                                                           | Replacement                                                      |
 | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `auto` boolean                                                                    | `keyboard-activation="automatic"`                                |
+| `auto` boolean                                                                    | `keyboard-activation` (see default change note below)            |
 | `compact` boolean                                                                 | `density="compact"`                                              |
 | `quiet` boolean                                                                   | No replacement; not part of Spectrum 2 surface                   |
 | `emphasized` boolean                                                              | No replacement; not part of Spectrum 2 surface                   |
@@ -67,6 +67,8 @@ import '@adobe/spectrum-wc/components/tabs/swc-tab-panel.js';
 | `rovingTabindexController` field                                                  | Removed; keyboard navigation is internal                         |
 | `focusElement` getter                                                             | Removed; use `tabsEl.focus()`                                    |
 
+> **Default activation mode changed.** In Spectrum 1, `<sp-tabs>` defaulted to manual activation (`auto` omitted or `false`): arrow keys moved focus without changing selection until Enter, Space, or click. Spectrum 2 defaults `keyboard-activation` to `automatic` to match React Spectrum's `Tabs`, so arrow keys now select immediately by default. If you were relying on the implicit manual default (no `auto` attribute) and your tab panels are expensive to render or not fully in the DOM, add `keyboard-activation="manual"` explicitly.
+
 ## Update your code
 
 ### 1. Rename the tags and attributes
@@ -208,7 +210,7 @@ Spectrum 2 uses a different custom property prefix. Spectrum 1 overrides will no
 - [ ] Replace `<sp-tabs>` with `<swc-tabs>`, `<sp-tab>` with `<swc-tab>`, `<sp-tab-panel>` with `<swc-tab-panel>`
 - [ ] Rename `value` attribute to `tab-id` on every tab and tab panel
 - [ ] Rename `label` attribute to `accessible-label` on `<swc-tabs>`
-- [ ] Replace boolean `auto` with `keyboard-activation="automatic"`
+- [ ] Replace boolean `auto` with `keyboard-activation`; if you relied on the implicit manual default in Spectrum 1, add `keyboard-activation="manual"` explicitly since Spectrum 2 defaults to `automatic`
 - [ ] Replace boolean `compact` with `density="compact"`
 - [ ] Remove `quiet`, `emphasized`, and `size` attributes
 - [ ] Replace `direction="vertical-right"` with `direction="vertical"`

2nd-gen/packages/swc/components/tabs/stories/tabs.stories.ts

@@ -63,7 +63,7 @@ export const meta: Meta = {
     selected: '1',
     'accessible-label': 'Product details',
     direction: 'horizontal',
-    'keyboard-activation': 'manual',
+    'keyboard-activation': 'automatic',
     density: 'regular',
     disabled: false,
   },
@@ -75,7 +75,7 @@ export const meta: Meta = {
       accessibleLabel: (raw['accessible-label'] ?? 'Product details') as string,
       direction: args.direction as TabsDirection,
       keyboardActivation: (raw['keyboard-activation'] ??
-        'manual') as KeyboardActivation,
+        'automatic') as KeyboardActivation,
       density: args.density as TabDensity,
       disabled: Boolean(args.disabled),
     });
@@ -145,7 +145,7 @@ const renderTabGroup = ({
   direction = 'horizontal',
   accessibleLabel = 'Product details',
   selected = '1',
-  keyboardActivation = 'manual',
+  keyboardActivation = 'automatic',
   density = 'regular',
   disabled = false,
   tabs = defaultTabs,
@@ -316,25 +316,25 @@ export const States: Story = {
 
 export const ActivationModes: Story = {
   render: () => html`
-    <p><strong>Manual activation (default)</strong></p>
+    <p><strong>Automatic activation (default)</strong></p>
     ${renderTabGroup({
-      accessibleLabel: 'Manual activation',
+      accessibleLabel: 'Automatic activation',
       panels: html`
         <swc-tab-panel tab-id="1">
-          <p>Use arrow keys to move focus, then Enter or Space to select.</p>
+          <p>Arrow keys immediately select and display content.</p>
         </swc-tab-panel>
         <swc-tab-panel tab-id="2"><p>Specifications content.</p></swc-tab-panel>
         <swc-tab-panel tab-id="3"><p>Guidelines content.</p></swc-tab-panel>
       `,
     })}
     <br />
-    <p><strong>Automatic activation</strong></p>
+    <p><strong>Manual activation</strong></p>
     ${renderTabGroup({
-      keyboardActivation: 'automatic',
-      accessibleLabel: 'Automatic activation',
+      keyboardActivation: 'manual',
+      accessibleLabel: 'Manual activation',
       panels: html`
         <swc-tab-panel tab-id="1">
-          <p>Arrow keys immediately select and display content.</p>
+          <p>Use arrow keys to move focus, then Enter or Space to select.</p>
         </swc-tab-panel>
         <swc-tab-panel tab-id="2"><p>Specifications content.</p></swc-tab-panel>
         <swc-tab-panel tab-id="3"><p>Guidelines content.</p></swc-tab-panel>

2nd-gen/packages/swc/components/tabs/tabs.mdx

@@ -37,7 +37,7 @@ Properties that render visual content:
 - **accessible-label** (on `swc-tabs`): accessible name for the tablist
 - **aria-label** (on `swc-tab`): accessible name for icon-only tabs
 - **direction**: layout direction (`horizontal` or `vertical`)
-- **keyboard-activation**: `manual` (default) or `automatic` (selection follows focus)
+- **keyboard-activation**: `automatic` (default; selection follows focus) or `manual`
 - **density**: `regular` (default) or `compact` spacing
 
 <Canvas of={TabsStories.Anatomy} />
@@ -80,9 +80,9 @@ Disabled tabs remain focusable via arrow keys but cannot be activated; see the [
 
 ### Activation Modes
 
-`keyboard-activation="manual"` (default): arrow keys move focus between tabs without changing the selected tab until Enter or Space.
+`keyboard-activation="automatic"` (default): selection follows focus when arrowing, matching React Spectrum's `Tabs` behavior.
 
-`keyboard-activation="automatic"`: selection follows focus when arrowing.
+`keyboard-activation="manual"`: arrow keys move focus between tabs without changing the selected tab until Enter or Space. Prefer this when tab panels are expensive to render or not fully present in the DOM.
 
 #### Events
 
@@ -114,7 +114,7 @@ The `<swc-tabs>` component implements several accessibility features:
 - <kbd>Home</kbd>: moves focus to the first tab
 - <kbd>End</kbd>: moves focus to the last tab
 - <kbd>Space</kbd> / <kbd>Enter</kbd>: activates the focused tab (manual mode).
-  In automatic activation, tabs activate when focused via arrows.
+  In automatic activation (default), tabs activate when focused via arrows.
 
 #### ARIA implementation
 

2nd-gen/packages/swc/components/tabs/test/tabs.test.ts

@@ -59,7 +59,7 @@ export const OverviewTest: Story = {
         'horizontal'
       );
       expect(tabs.keyboardActivation, 'default keyboard activation').toBe(
-        'manual'
+        'automatic'
       );
       expect(tabs.density, 'default density is regular').toBe('regular');
       expect(tabs.disabled, 'default disabled is false').toBe(false);
@@ -288,24 +288,29 @@ export const HostAutoDisabledReactiveTest: Story = {
     const tab2 = canvasElement.querySelector('swc-tab[tab-id="2"]') as Tab;
 
     await step(
-      'manual mode: arrow moves focus without changing selection',
+      'automatic mode (default): arrow selects focused tab',
       async () => {
-        expect(tabs.keyboardActivation, 'starts in manual mode').toBe('manual');
+        expect(tabs.keyboardActivation, 'starts in automatic mode').toBe(
+          'automatic'
+        );
         tab1.focus();
         tab1.dispatchEvent(
           new KeyboardEvent('keydown', { code: 'ArrowRight', bubbles: true })
         );
         await tabs.updateComplete;
         expect(tabs.ownerDocument.activeElement, 'focus on tab 2').toBe(tab2);
-        expect(tabs.selected, 'selection unchanged in manual mode').toBe('1');
+        expect(tabs.selected, 'selection follows focus in automatic mode').toBe(
+          '2'
+        );
       }
     );
 
-    await step('automatic mode: arrow then selects focused tab', async () => {
-      tabs.keyboardActivation = 'automatic';
+    await step('manual mode: arrow moves focus without selecting', async () => {
+      tabs.keyboardActivation = 'manual';
+      tabs.selected = '1';
       await tabs.updateComplete;
-      expect(tabs.keyboardActivation, 'keyboard activation is automatic').toBe(
-        'automatic'
+      expect(tabs.keyboardActivation, 'keyboard activation is manual').toBe(
+        'manual'
       );
 
       tab1.focus();
@@ -317,9 +322,7 @@ export const HostAutoDisabledReactiveTest: Story = {
         tabs.ownerDocument.activeElement,
         'focus on tab 2 after arrow'
       ).toBe(tab2);
-      expect(tabs.selected, 'selection follows focus in automatic mode').toBe(
-        '2'
-      );
+      expect(tabs.selected, 'selection unchanged in manual mode').toBe('1');
     });
 
     await step(
@@ -900,7 +903,11 @@ export const HomeEndKeyTest: Story = {
 
 export const EnterSpaceActivationTest: Story = {
   render: () => html`
-    <swc-tabs selected="1" accessible-label="Activation test">
+    <swc-tabs
+      selected="1"
+      keyboard-activation="manual"
+      accessible-label="Activation test"
+    >
       <swc-tab tab-id="1">Tab 1</swc-tab>
       <swc-tab tab-id="2">Tab 2</swc-tab>
       <swc-tab-panel tab-id="1"><p>Panel 1</p></swc-tab-panel>

CONTRIBUTOR-DOCS/03_project-planning/03_components/tabs/accessibility-migration-analysis.md

@@ -142,7 +142,7 @@ This doc describes how `swc-tabs` (with `swc-tab` and `swc-tab-panel`) should be
 | [Focus order (WCAG 2.4.3)](https://www.w3.org/TR/WCAG22/#focus-order) | Tab from the tablist should move to meaningful content (`tabpanel` with `tabindex="0"` when needed, or first focusable in panel) per APG guidance. |
 | [Name, role, value (WCAG 4.1.2)](https://www.w3.org/TR/WCAG22/#name-role-value) | Each tab needs a name; state (`aria-selected`) must update; panels hidden with `hidden` or equivalent must not leave stale state exposed. |
 
-**Bottom line:** Choose automatic vs manual activation from real performance and DOM shape; implement APG keyboard tables for the chosen model; keep tab↔panel references valid in the composed tree (see Shadow DOM below).
+**Bottom line:** Choose automatic vs manual activation from real performance and DOM shape; implement APG keyboard tables for the chosen model; keep tab↔panel references valid in the composed tree (see Shadow DOM below). For `swc-tabs`, that resolved to `automatic` as the default (Q20 in migration-plan.md): panel content is always in the light DOM, and matching React Spectrum/React Aria `Tabs` was prioritized once the APG precondition for automatic activation was confirmed to hold.
 
 ---
 
@@ -167,7 +167,7 @@ This doc describes how `swc-tabs` (with `swc-tab` and `swc-tab-panel`) should be
 | **Hidden panels** | Inactive panels use `hidden` (or visibility/display patterns that hide from AT) per APG; do not leave inert content falsely exposed. |
 | **`tabindex` on `tabpanel`** | Per [automatic activation example](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-automatic/), `tabindex="0"` on `tabpanel` helps users move from tablist into panel content when the first element inside is not focusable. [Manual example](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-manual/) may omit `tabpanel` tabindex when the first child is focusable — match APG for your story variants. |
 | **Vertical orientation** | If the tablist is vertical, set `aria-orientation="vertical"` and arrow key mapping consistent with APG (Up/Down or Left/Right per spec and docs). |
-| **Activation mode (API)** | Mirror 1st-gen `auto` (boolean, default off = manual): `auto` false — arrows move focus only; Enter, Space, or click select; `auto` true — selection follows focus when arrows move between tabs. Document and test both modes; default manual matches lazy or heavy panels. |
+| **Activation mode (API)** | Expose both modes via `keyboard-activation`: `manual` — arrows move focus only; Enter, Space, or click select; `automatic` — selection follows focus when arrows move between tabs. Document and test both modes. **Superseded (Q20, see migration-plan.md):** default is `automatic`, not `manual`, to match React Spectrum/React Aria `Tabs` — `swc-tab-panel` content is always in the light DOM (not lazily mounted), so the "default manual matches lazy or heavy panels" reasoning below does not apply to our default; it's retained as guidance for consumers who lazy-render their own panel content. |
 
 ### Shadow DOM and cross-root ARIA Issues
 
@@ -225,7 +225,7 @@ When implementation gaps appear, classify missing behavior:
 ## Summary checklist
 
 - [ ] `tablist` / `tab` / `tabpanel` roles and labelling match APG.
-- [ ] Automatic vs manual activation documented and tested; default matches content loading model.
+- [x] Automatic vs manual activation documented and tested; default is `automatic` (Q20), matching React Spectrum/React Aria `Tabs` and the component's always-in-DOM panel content.
 - [ ] Roving `tabindex` and arrows use `FocusgroupNavigationController` where appropriate ([#6129](https://github.com/adobe/spectrum-web-components/pull/6129)); tabs-only logic stays in component unless promoted to shared infra deliberately.
 - [ ] `aria-controls` / `aria-labelledby` valid in composed tree (no silent cross-root ID failures).
 - [ ] `tabpanel` focus behavior matches APG for focusable vs non-focusable first content.