feat: Add native attributes for button dropdown (#3700)

Author: gethinwebster

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -5680,6 +5680,77 @@ The main action also supports the following properties of the [button](/componen
       "optional": true,
       "type": "ButtonDropdownProps.MainAction",
     },
+    {
+      "description": "Attributes to add to the native element of the \`mainAction\`.
+
+Specify either \`button\` for a standard main action, or \`anchor\` if \`html\` is set.
+
+Some attributes will be automatically combined with internal attribute values:
+- \`className\` will be appended.
+- Event handlers will be chained, unless the default is prevented.
+
+We do not support using this attribute to apply custom styling.",
+      "inlineType": {
+        "name": "object",
+        "properties": [
+          {
+            "inlineType": {
+              "name": "Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "children"> & Record<\`data-\${string}\`, string>",
+              "type": "union",
+              "values": [
+                "Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "children">",
+                "Record<\`data-\${string}\`, string>",
+              ],
+            },
+            "name": "anchor",
+            "optional": true,
+            "type": "Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "children"> & Record<\`data-\${string}\`, string>",
+          },
+          {
+            "inlineType": {
+              "name": "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & Record<\`data-\${string}\`, string>",
+              "type": "union",
+              "values": [
+                "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children">",
+                "Record<\`data-\${string}\`, string>",
+              ],
+            },
+            "name": "button",
+            "optional": true,
+            "type": "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & Record<\`data-\${string}\`, string>",
+          },
+        ],
+        "type": "object",
+      },
+      "name": "nativeMainActionAttributes",
+      "optional": true,
+      "systemTags": [
+        "core",
+      ],
+      "type": "{ button?: NativeAttributes<React.ButtonHTMLAttributes<HTMLButtonElement>>; anchor?: NativeAttributes<React.AnchorHTMLAttributes<HTMLAnchorElement>>; }",
+    },
+    {
+      "description": "Attributes to add to the native \`button\` element.
+Some attributes will be automatically combined with internal attribute values:
+- \`className\` will be appended.
+- Event handlers will be chained, unless the default is prevented.
+
+We do not support using this attribute to apply custom styling.",
+      "inlineType": {
+        "name": "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & Record<\`data-\${string}\`, string>",
+        "type": "union",
+        "values": [
+          "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children">",
+          "Record<\`data-\${string}\`, string>",
+        ],
+      },
+      "name": "nativeTriggerAttributes",
+      "optional": true,
+      "systemTags": [
+        "core",
+      ],
+      "type": "Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & Record<\`data-\${string}\`, string>",
+    },
     {
       "defaultValue": "'normal'",
       "description": "Determines the general styling of the button dropdown.

src/button-dropdown/__tests__/button-dropdown.test.tsx

@@ -492,3 +492,50 @@ test('checkbox item test util should return null if not a checkbox item', () =>
   // findItemValueById should return the value if item checkbox
   expect(wrapper.findItemCheckedById('i5')).toBe('true');
 });
+
+describe('native attributes', () => {
+  test('adds nativeTriggerAttributes', () => {
+    const wrapper = renderButtonDropdown({
+      items,
+      nativeTriggerAttributes: {
+        'aria-describedby': 'my-custom-description',
+      },
+    });
+    expect(wrapper.findTriggerButton()?.getElement()).toHaveAttribute('aria-describedby', 'my-custom-description');
+  });
+  test('adds nativeTriggerAttributes but not to mainAction', () => {
+    const wrapper = renderButtonDropdown({
+      items,
+      mainAction: { text: 'Main' },
+      nativeTriggerAttributes: {
+        'aria-describedby': 'my-custom-description',
+      },
+    });
+    expect(wrapper.findTriggerButton()?.getElement()).toHaveAttribute('aria-describedby', 'my-custom-description');
+    expect(wrapper.findMainAction()?.getElement()).not.toHaveAttribute('aria-describedby', 'my-custom-description');
+  });
+  test('adds nativeMainActionAttributes to button-style mainAction', () => {
+    const wrapper = renderButtonDropdown({
+      items,
+      mainAction: { text: 'Main' },
+      nativeMainActionAttributes: {
+        button: {
+          'aria-describedby': 'my-custom-description',
+        },
+      },
+    });
+    expect(wrapper.findMainAction()?.getElement()).toHaveAttribute('aria-describedby', 'my-custom-description');
+  });
+  test('adds nativeMainActionAttributes to link-style mainAction', () => {
+    const wrapper = renderButtonDropdown({
+      items,
+      mainAction: { text: 'Main', href: '#' },
+      nativeMainActionAttributes: {
+        anchor: {
+          'aria-describedby': 'my-custom-description',
+        },
+      },
+    });
+    expect(wrapper.findMainAction()?.getElement()).toHaveAttribute('aria-describedby', 'my-custom-description');
+  });
+});

src/button-dropdown/index.tsx

@@ -34,6 +34,8 @@ const ButtonDropdown = React.forwardRef(
       onItemFollow,
       mainAction,
       fullWidth,
+      nativeMainActionAttributes,
+      nativeTriggerAttributes,
       ...props
     }: ButtonDropdownProps,
     ref: React.Ref<ButtonDropdownProps.Ref>
@@ -73,6 +75,8 @@ const ButtonDropdown = React.forwardRef(
         onItemFollow={onItemFollow}
         mainAction={mainAction}
         fullWidth={fullWidth}
+        nativeMainActionAttributes={nativeMainActionAttributes}
+        nativeTriggerAttributes={nativeTriggerAttributes}
         {...getAnalyticsMetadataAttribute({
           component: analyticsComponentMetadata,
         })}

src/button-dropdown/interfaces.ts

@@ -10,6 +10,10 @@ import { BaseComponentProps } from '../internal/base-component';
 import { ExpandToViewport } from '../internal/components/dropdown/interfaces';
 import { BaseNavigationDetail, CancelableEventHandler } from '../internal/events';
 import { InternalBaseComponentProps } from '../internal/hooks/use-base-component';
+/**
+ * @awsuiSystem core
+ */
+import { NativeAttributes } from '../internal/utils/with-native-attributes';
 
 export interface ButtonDropdownProps extends BaseComponentProps, ExpandToViewport {
   /**
@@ -119,6 +123,36 @@ export interface ButtonDropdownProps extends BaseComponentProps, ExpandToViewpor
    * Sets the button width to be 100% of the parent container width. Button content is centered.
    */
   fullWidth?: boolean;
+
+  /**
+   * Attributes to add to the native `button` element.
+   * Some attributes will be automatically combined with internal attribute values:
+   * - `className` will be appended.
+   * - Event handlers will be chained, unless the default is prevented.
+   *
+   * We do not support using this attribute to apply custom styling.
+   *
+   * @awsuiSystem core
+   */
+  nativeTriggerAttributes?: NativeAttributes<React.ButtonHTMLAttributes<HTMLButtonElement>>;
+
+  /**
+   * Attributes to add to the native element of the `mainAction`.
+   *
+   * Specify either `button` for a standard main action, or `anchor` if `html` is set.
+   *
+   * Some attributes will be automatically combined with internal attribute values:
+   * - `className` will be appended.
+   * - Event handlers will be chained, unless the default is prevented.
+   *
+   * We do not support using this attribute to apply custom styling.
+   *
+   * @awsuiSystem core
+   */
+  nativeMainActionAttributes?: {
+    button?: NativeAttributes<React.ButtonHTMLAttributes<HTMLButtonElement>>;
+    anchor?: NativeAttributes<React.AnchorHTMLAttributes<HTMLAnchorElement>>;
+  };
 }
 
 export namespace ButtonDropdownProps {

src/button-dropdown/internal.tsx

@@ -56,6 +56,8 @@ const InternalButtonDropdown = React.forwardRef(
       linkStyle,
       fullWidth,
       position,
+      nativeMainActionAttributes,
+      nativeTriggerAttributes,
       ...props
     }: InternalButtonDropdownProps,
     ref: React.Ref<ButtonDropdownProps.Ref>
@@ -76,7 +78,7 @@ const InternalButtonDropdown = React.forwardRef(
         warnOnce('ButtonDropdown', 'Main action is only supported for "primary" and "normal" component variant.');
       }
     }
-    const isMainAction = mainAction && (variant === 'primary' || variant === 'normal');
+    const hasMainAction = mainAction && (variant === 'primary' || variant === 'normal');
     const isVisualRefresh = useVisualRefresh();
 
     const {
@@ -117,13 +119,13 @@ const InternalButtonDropdown = React.forwardRef(
       ref,
       () => ({
         focus(...args) {
-          (isMainAction ? mainActionRef : triggerRef).current?.focus(...args);
+          (hasMainAction ? mainActionRef : triggerRef).current?.focus(...args);
         },
         focusDropdownTrigger(...args) {
           triggerRef.current?.focus(...args);
         },
       }),
-      [mainActionRef, triggerRef, isMainAction]
+      [mainActionRef, triggerRef, hasMainAction]
     );
 
     const clickHandler = () => {
@@ -170,6 +172,7 @@ const InternalButtonDropdown = React.forwardRef(
       formAction: 'none',
       nativeButtonAttributes: {
         'aria-haspopup': true,
+        ...nativeTriggerAttributes,
       },
     };
 
@@ -222,7 +225,7 @@ const InternalButtonDropdown = React.forwardRef(
           })}
         </div>
       );
-    } else if (isMainAction) {
+    } else if (hasMainAction) {
       const { text, iconName, iconAlt, iconSvg, iconUrl, external, externalIconAriaLabel, ...mainActionProps } =
         mainAction;
       const mainActionIconProps = external
@@ -247,6 +250,8 @@ const InternalButtonDropdown = React.forwardRef(
           variant={variant}
           ariaLabel={mainActionAriaLabel}
           formAction="none"
+          nativeAnchorAttributes={nativeMainActionAttributes?.anchor}
+          nativeButtonAttributes={nativeMainActionAttributes?.button}
         >
           {text}
         </InternalButton>