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,89 @@ describe('processMetadata', () => {
 
     document.body.removeChild(mockDiv);
   });
+
+  test('extracts component description from aria-describedby when label is present', () => {
+    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 no aria-describedby exists', () => {
+    const mockDiv = document.createElement('div');
+    mockDiv.innerHTML = `<input />`;
+    document.body.appendChild(mockDiv);
+
+    const result: any = processMetadata(mockDiv, { name: 'awsui.Input', label: 'input' });
+    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 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('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);
+  });
 });
 
 describe('merge', () => {

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

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { GeneratedAnalyticsMetadataFragment } from './interfaces.js';
+import { GeneratedAnalyticsMetadataFragment, LabelIdentifier } from './interfaces.js';
 import { processLabel } from './labels-utils.js';
 import type { GetComponentsTreeOptions, OptionItem, TabItem } from './page-scanner-utils.js';
 
@@ -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,15 @@ export const processMetadata = (
     }
     return acc;
   }, {});
+
+  if (result.name && node && localMetadata.label) {
+    const description = resolveComponentDescription(node, localMetadata.label);
+    if (description) {
+      result.description = description;
+    }
+  }
+
+  return result;
 };
 
 const isNil = (value: any) => {
@@ -159,6 +168,25 @@ const resolveInputDescription = (root: HTMLElement, input: HTMLElement): string
   return '';
 };
 
+const resolveComponentDescription = (node: HTMLElement, labelSelector: string | LabelIdentifier): string => {
+  const selector = typeof labelSelector === 'string' ? labelSelector : labelSelector.selector;
+  const firstSelector = Array.isArray(selector) ? selector[0] : selector;
+  const el = firstSelector ? node.querySelector(firstSelector) : 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>;
 }