fix(ui): harden codetabs deep links

Author: joebasrawi

.changeset/codetabs-anchor-deeplinks.md

@@ -1,5 +1,9 @@
 ---
-'@node-core/ui-components': minor
+'@node-core/ui-components': major
 ---
 
-Add HTML/CSS `:target` deep linking to CodeTabs and replace Radix Tabs for that component so fragments work without JavaScript hash listeners.
+Add URL-fragment deep links to CodeTabs. CSS selects the visible panel without JavaScript; a client enhancement keeps keyboard navigation and ARIA state in sync with the fragment.
+
+CodeTabs now expects one raw child per tab, in tab order. Replace Radix `Tabs.Content` children with their contents. Arrays and fragments are supported; components that internally render multiple panels must be expanded at the call site. This replaces the previous Radix context and is a breaking change for direct CodeTabs consumers. The MDX wrapper remains compatible.
+
+Use a unique `groupId` for durable links. Fragments are `{slug(groupId)}-{slug(tabKey)}-{index}`; reordering tabs changes them. Generated instance prefixes avoid collisions but are not a permanent URL contract.

apps/site/tests/e2e/code-tabs.spec.ts

@@ -0,0 +1,57 @@
+import { expect, test } from '@playwright/test';
+
+test('code tabs support keyboard selection, deep links, and browser history', async ({
+  page,
+}) => {
+  await page.goto('/en');
+  const tabs = page
+    .getByRole('tablist', { name: 'Code samples' })
+    .getByRole('tab');
+  const first = tabs.first();
+  const second = tabs.nth(1);
+  const firstId = await first.getAttribute('aria-controls');
+  const secondId = await second.getAttribute('aria-controls');
+
+  await first.focus();
+  await page.keyboard.press('ArrowRight');
+  await expect(second).toBeFocused();
+  await expect(second).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator(`[id="${secondId}"]`)).toBeVisible();
+  await expect(page.locator(`[id="${firstId}"]`)).toBeHidden();
+
+  await page.reload();
+  await expect(second).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator(`[id="${secondId}"]`)).toBeVisible();
+  await first.click();
+  await expect(page.locator(`[id="${firstId}"]`)).toBeVisible();
+  await page.goBack();
+  await expect(second).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator(`[id="${secondId}"]`)).toBeVisible();
+  await page.goForward();
+  await expect(first).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator(`[id="${firstId}"]`)).toBeVisible();
+});
+
+test.describe('without JavaScript', () => {
+  test.use({ javaScriptEnabled: false });
+
+  test('native links select visible panels and survive a reload', async ({
+    page,
+  }) => {
+    await page.goto('/en');
+    const links = page
+      .getByRole('navigation', { name: 'Code samples' })
+      .getByRole('link');
+    const firstId = await links.first().getAttribute('aria-controls');
+    const second = links.nth(1);
+    const secondId = await second.getAttribute('aria-controls');
+    await expect(page.locator(`[id="${firstId}"]`)).toBeVisible();
+    await expect(page.locator(`[id="${secondId}"]`)).toBeHidden();
+    await second.click();
+    await expect(page.locator(`[id="${secondId}"]`)).toBeVisible();
+    await expect(page.locator(`[id="${firstId}"]`)).toBeHidden();
+    await page.reload();
+    await expect(page.locator(`[id="${secondId}"]`)).toBeVisible();
+    await expect(page.locator(`[id="${firstId}"]`)).toBeHidden();
+  });
+});

packages/ui-components/package.json

@@ -85,6 +85,7 @@
     "postcss-calc": "~10.1.1",
     "postcss-cli": "^11.0.1",
     "postcss-loader": "8.2.1",
+    "react-dom": "^19.2.8",
     "storybook": "~10.5.4",
     "style-loader": "4.0.0",
     "stylelint": "17.14.1",

packages/ui-components/src/Common/CodeTabs/__tests__/getCodeTabId.test.mjs

@@ -4,20 +4,27 @@ import { describe, it } from 'node:test';
 import { getCodeTabId, slugifyIdSegment } from '../getCodeTabId';
 
 describe('getCodeTabId', () => {
-  it('builds `{groupId}-{tabKey}` fragments', () => {
-    assert.equal(getCodeTabId('install', 'js-0'), 'install-js-0');
-    assert.equal(getCodeTabId('install', 'cjs-1'), 'install-cjs-1');
+  it('includes the tab index in fragments', () => {
+    assert.equal(getCodeTabId('install', 'js', 0), 'install-js-0');
+    assert.equal(getCodeTabId('install', 'cjs', 1), 'install-cjs-1');
   });
 
   it('slugifies labels and prefixes numeric segments', () => {
     assert.equal(slugifyIdSegment('Hello World'), 'hello-world');
     assert.equal(slugifyIdSegment('123'), 'id-123');
     assert.equal(slugifyIdSegment('codetabs-:r1:'), 'codetabs-r1');
-    assert.equal(getCodeTabId('Install Steps', 'C++'), 'install-steps-c');
+    assert.equal(getCodeTabId('install-steps', 'C++', 0), 'install-steps-c-0');
   });
 
   it('falls back to `tab` for empty input', () => {
     assert.equal(slugifyIdSegment('   '), 'tab');
-    assert.equal(getCodeTabId('', 'js'), 'tab-js');
+    assert.equal(getCodeTabId('install', '', 0), 'install-tab-0');
+  });
+
+  it('preserves case in the prepared React instance prefix', () => {
+    assert.notEqual(
+      getCodeTabId('codetabs-R1', 'js', 0),
+      getCodeTabId('codetabs-r1', 'js', 0)
+    );
   });
 });