feat: Extract component description from aria-describedby

Add description field to component metadata tree output. When a
component has a label extracted, the toolkit now also resolves
aria-describedby on the first child element that has it, concatenating
all referenced IDs' text content (matching screen reader behavior).

This enables consumers like the page scanner to access constraint text,
descriptions, and other accessible descriptions alongside labels.

Author: gethinwebster

src/internal/analytics-metadata/__tests__/metadata-utils.test.ts

@@ -337,6 +337,109 @@ describe('processMetadata', () => {
 
     document.body.removeChild(mockDiv);
   });
+
+  test('extracts component description from aria-describedby on label element', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <span id="desc-1">Must be 3-20 characters</span>
+      <input aria-describedby="desc-1" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.Input', label: 'input' });
+    expect(result.description).toBe('Must be 3-20 characters');
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('concatenates multiple aria-describedby IDs', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <span id="desc-a">Enter your work email</span>
+      <span id="desc-b">Must end with @amazon.com</span>
+      <input aria-describedby="desc-a desc-b" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.Input', label: 'input' });
+    expect(result.description).toBe('Enter your work email Must end with @amazon.com');
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('does not extract description when label element has no aria-describedby', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <label class="label">Form field label</label>
+      <div id="ff-desc">This is a description</div>
+      <input aria-describedby="ff-desc" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.FormField', label: '.label' });
+    expect(result.description).toBeUndefined();
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('does not extract description when component has no label selector', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <span id="desc-1">Some description</span>
+      <input aria-describedby="desc-1" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.Input' });
+    expect(result.description).toBeUndefined();
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('does not extract description from child elements', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <div id="ff-desc">This is a description</div>
+      <input aria-describedby="ff-desc" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.FormField', label: '.label' });
+    expect(result.description).toBeUndefined();
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('skips missing IDs in aria-describedby', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <span id="desc-exists">Constraint text</span>
+      <input aria-describedby="desc-missing desc-exists" />
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.Input', label: 'input' });
+    expect(result.description).toBe('Constraint text');
+
+    document.body.removeChild(mockDiv);
+  });
+
+  test('extracts description when label is a LabelIdentifier with array selector', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `
+      <span id="desc-1">Help text</span>
+      <button class="trigger" aria-describedby="desc-1">Select</button>
+    `;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, {
+      name: 'awsui.Select',
+      label: { selector: ['.trigger', '.fallback'] },
+    });
+    expect(result.description).toBe('Help text');
+
+    document.body.removeChild(mockDiv);
+  });
 });
 
 describe('merge', () => {

src/internal/analytics-metadata/metadata-utils.ts

@@ -22,7 +22,7 @@ export const processMetadata = (
   localMetadata: any,
   options?: GetComponentsTreeOptions
 ): GeneratedAnalyticsMetadataFragment => {
-  return Object.keys(localMetadata).reduce((acc: any, key: string) => {
+  const result: any = Object.keys(localMetadata).reduce((acc: any, key: string) => {
     if (key.toLowerCase().match(/labels$/)) {
       acc[key] = processLabel(node, localMetadata[key], 'multi');
     } else if (key.toLowerCase().match(/label$/)) {
@@ -68,6 +68,21 @@ export const processMetadata = (
     }
     return acc;
   }, {});
+
+  if (result.name && node && localMetadata.label) {
+    const labelSelector =
+      typeof localMetadata.label === 'string'
+        ? localMetadata.label
+        : Array.isArray(localMetadata.label.selector)
+        ? localMetadata.label.selector[0]
+        : localMetadata.label.selector || '';
+    const description = resolveComponentDescription(node, labelSelector);
+    if (description) {
+      result.description = description;
+    }
+  }
+
+  return result;
 };
 
 const isNil = (value: any) => {
@@ -159,6 +174,23 @@ const resolveInputDescription = (root: HTMLElement, input: HTMLElement): string
   return '';
 };
 
+const resolveComponentDescription = (node: HTMLElement, labelSelector: string): string => {
+  const el = labelSelector ? node.querySelector(labelSelector) : node;
+  if (!el) {
+    return '';
+  }
+  const describedBy = el.getAttribute('aria-describedby');
+  if (!describedBy) {
+    return '';
+  }
+  const doc = node.ownerDocument || document;
+  return describedBy
+    .split(' ')
+    .map(id => doc.getElementById(id)?.textContent?.trim() || '')
+    .filter(Boolean)
+    .join(' ');
+};
+
 const getRadioGroupOptions = (node: HTMLElement): Array<OptionItem> => {
   const inputs = Array.from(node.querySelectorAll('input[type="radio"]')) as HTMLElement[];
   return inputs

src/internal/analytics-metadata/page-scanner-utils.ts

@@ -8,6 +8,7 @@ import { getGeneratedAnalyticsMetadata } from './utils.js';
 interface GeneratedAnalyticsMetadataComponentTree {
   name: string;
   label: string;
+  description?: string;
   properties?: Record<string, string | Array<string> | Array<Array<string>> | Array<OptionItem> | Array<TabItem>>;
   children?: Array<GeneratedAnalyticsMetadataComponentTree>;
 }