From 74a94a47c48a3db04359c8a28a8d4fa9e360d3d2 Mon Sep 17 00:00:00 2001
From: Andrey Goder <andy.goder@gmail.com>
Date: Thu, 6 Aug 2026 00:53:02 -0700
Subject: [PATCH] Forward a shared set of button props across the *Button
 components

ChatSendButton was a closed props interface with no passthrough, so
consumers could not attach `aria-describedby`, `aria-keyshortcuts`,
`id`, `form`, or focus/keyboard handlers to it. ChatScrollButton had
the opposite problem: it extended `ComponentPropsWithoutRef<'div'>`
and spread arbitrary DOM props onto its wrapper.

Introduce `ButtonPassthroughProps`, a curated `Pick` of `ButtonProps`
covering identity, description, and interaction, and extend every
button-like component with it so they all forward the same set to the
button they render. Button itself gains the two members it was missing
(`id`, `onFocus`); ActionElement already spread unlisted props, so it
only needed the `onFocus` type.

ChatScrollButton now forwards to the inner Button rather than the
wrapper div, since that is the interactive element the props describe.

Fixes #371

Claude-Session: https://claude.ai/code/session_01XFkkvUQfynGRedEYDNxKoY
---
 src/components/Button/Button.test.tsx         | 23 ++++++++++++
 src/components/Button/Button.tsx              | 32 ++++++++++++++++
 src/components/Button/index.ts                |  1 +
 src/components/Chat/Chat.test.tsx             | 25 +++++++++++++
 src/components/Chat/ChatComposer.test.tsx     | 37 +++++++++++++++++++
 src/components/Chat/ChatScrollButton.tsx      | 13 +++----
 src/components/Chat/ChatSendButton.tsx        |  6 ++-
 src/components/CopyButton/CopyButton.test.tsx | 25 +++++++++++++
 src/components/CopyButton/CopyButton.tsx      | 31 ++++++++++------
 .../SplitButton/SplitButton.test.tsx          | 23 ++++++++++++
 src/components/SplitButton/SplitButton.tsx    | 17 ++++++---
 .../ToggleButton/ToggleButton.test.tsx        | 22 +++++++++++
 src/components/ToggleButton/ToggleButton.tsx  |  6 ++-
 src/index.ts                                  |  7 +++-
 src/internal/ActionElement.tsx                |  2 +
 15 files changed, 241 insertions(+), 29 deletions(-)

diff --git a/src/components/Button/Button.test.tsx b/src/components/Button/Button.test.tsx
index eec7cd4a..66539e13 100644
--- a/src/components/Button/Button.test.tsx
+++ b/src/components/Button/Button.test.tsx
@@ -599,4 +599,27 @@ describe('Button', () => {
 
     warn.mockRestore();
   });
+
+  it('applies id and fires onFocus on both the button and the link', async () => {
+    const user = userEvent.setup();
+    const onFocus = vi.fn();
+    const {rerender} = render(
+      <Button id="save" label="Save" onFocus={onFocus} />,
+    );
+
+    const button = screen.getByRole('button', {name: 'Save'});
+    expect(button).toHaveAttribute('id', 'save');
+
+    await user.tab();
+    expect(button).toHaveFocus();
+    expect(onFocus).toHaveBeenCalledOnce();
+
+    rerender(<Button href="/save" id="save" label="Save" onFocus={onFocus} />);
+
+    const link = screen.getByRole('link', {name: 'Save'});
+    expect(link).toHaveAttribute('id', 'save');
+
+    link.focus();
+    expect(onFocus).toHaveBeenCalledTimes(2);
+  });
 });
diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index b2b1baaa..ac649add 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -2,6 +2,7 @@
 
 import type {
   CSSProperties,
+  FocusEventHandler,
   JSX,
   KeyboardEvent,
   MouseEvent,
@@ -113,6 +114,10 @@ interface ButtonBaseProps {
    * renders as a link element.
    */
   href?: string;
+  /**
+   * HTML `id` attribute applied to the root element.
+   */
+  id?: string;
   /**
    * Whether the button is disabled. Prevents interaction and applies disabled
    * styling.
@@ -136,6 +141,10 @@ interface ButtonBaseProps {
    * Click event handler.
    */
   onClick?: MouseEventHandler<HTMLElement>;
+  /**
+   * Focus event handler for the root element.
+   */
+  onFocus?: FocusEventHandler<HTMLElement>;
   /**
    * Keyboard event handler for the root element.
    */
@@ -218,6 +227,25 @@ export type ButtonProps =
       isIconOnly?: false;
     });
 
+/**
+ * The identity, description, and interaction props every button-like component
+ * in the library forwards to the button it renders.
+ */
+export type ButtonPassthroughProps = Pick<
+  ButtonProps,
+  | 'aria-controls'
+  | 'aria-describedby'
+  | 'aria-details'
+  | 'aria-expanded'
+  | 'aria-haspopup'
+  | 'aria-keyshortcuts'
+  | 'aria-labelledby'
+  | 'form'
+  | 'id'
+  | 'onFocus'
+  | 'onKeyDown'
+>;
+
 export function Button({
   label,
   'aria-controls': ariaControls,
@@ -252,8 +280,10 @@ export function Button({
   startContent,
   tooltip,
   onClick,
+  onFocus,
   onKeyDown,
   form,
+  id,
   name,
   value,
   width,
@@ -379,12 +409,14 @@ export function Button({
       data-testid={dataTestId}
       form={form}
       href={renderAsLink ? href : undefined}
+      id={id}
       isDisabled={
         !renderAsLink && !useAriaDisabled ? buttonDisabled : undefined
       }
       isLink={renderAsLink}
       name={name}
       onClick={renderAsLink ? handleLinkClick : handleButtonClick}
+      onFocus={onFocus}
       onKeyDown={renderAsLink ? handleLinkKeyDown : handleButtonKeyDown}
       ref={ref}
       rel={renderAsLink ? linkRel : undefined}
diff --git a/src/components/Button/index.ts b/src/components/Button/index.ts
index 3f7a913e..0f5201d8 100644
--- a/src/components/Button/index.ts
+++ b/src/components/Button/index.ts
@@ -1,5 +1,6 @@
 export {
   Button,
+  type ButtonPassthroughProps,
   type ButtonProps,
   type ButtonSize,
 } from 'components/Button/Button';
diff --git a/src/components/Chat/Chat.test.tsx b/src/components/Chat/Chat.test.tsx
index dcaa9c4b..defcead3 100644
--- a/src/components/Chat/Chat.test.tsx
+++ b/src/components/Chat/Chat.test.tsx
@@ -288,4 +288,29 @@ describe('ChatScrollButton', () => {
       screen.getByTestId('scroll-button').firstElementChild?.className,
     ).not.toBe(hiddenPill);
   });
+
+  it('forwards the shared button passthrough props to the button', () => {
+    render(
+      <>
+        <span id="scroll-hint">Jump to the latest message</span>
+        <ChatScrollButton
+          aria-describedby="scroll-hint"
+          aria-keyshortcuts="Meta+ArrowDown"
+          id="scroll-to-bottom"
+          isVisible
+          onClick={() => {}}
+        />
+      </>,
+    );
+
+    const button = screen.getByRole('button', {name: 'Scroll to bottom'});
+    expect(button).toHaveAttribute('id', 'scroll-to-bottom');
+    // The icon-only tooltip appends its own id, so the consumer's survives
+    // alongside it rather than replacing it.
+    expect(button).toHaveAttribute(
+      'aria-describedby',
+      expect.stringContaining('scroll-hint'),
+    );
+    expect(button).toHaveAttribute('aria-keyshortcuts', 'Meta+ArrowDown');
+  });
 });
diff --git a/src/components/Chat/ChatComposer.test.tsx b/src/components/Chat/ChatComposer.test.tsx
index 52e4db60..87e459ce 100644
--- a/src/components/Chat/ChatComposer.test.tsx
+++ b/src/components/Chat/ChatComposer.test.tsx
@@ -312,4 +312,41 @@ describe('ChatSendButton', () => {
     expect(onSend).toHaveBeenCalledOnce();
     expect(contextSubmit).not.toHaveBeenCalled();
   });
+
+  it('forwards the shared button passthrough props', async () => {
+    const user = userEvent.setup();
+    const onFocus = vi.fn();
+    const onKeyDown = vi.fn();
+    render(
+      <>
+        <span id="send-hint">Press to send</span>
+        <ChatSendButton
+          aria-describedby="send-hint"
+          aria-keyshortcuts="Meta+Enter"
+          form="composer-form"
+          id="send"
+          isDisabled={false}
+          onFocus={onFocus}
+          onKeyDown={onKeyDown}
+        />
+      </>,
+    );
+
+    const button = screen.getByRole('button', {name: 'Send'});
+    expect(button).toHaveAttribute('id', 'send');
+    // The icon-only tooltip appends its own id, so the consumer's survives
+    // alongside it rather than replacing it.
+    expect(button).toHaveAttribute(
+      'aria-describedby',
+      expect.stringContaining('send-hint'),
+    );
+    expect(button).toHaveAttribute('aria-keyshortcuts', 'Meta+Enter');
+    expect(button).toHaveAttribute('form', 'composer-form');
+
+    await user.click(button);
+    expect(onFocus).toHaveBeenCalledOnce();
+
+    await user.keyboard('a');
+    expect(onKeyDown).toHaveBeenCalledOnce();
+  });
 });
diff --git a/src/components/Chat/ChatScrollButton.tsx b/src/components/Chat/ChatScrollButton.tsx
index f542d015..c5e9ca79 100644
--- a/src/components/Chat/ChatScrollButton.tsx
+++ b/src/components/Chat/ChatScrollButton.tsx
@@ -1,15 +1,12 @@
 'use client';
 
 import {ChevronDown} from 'lucide-react';
-import type {ComponentPropsWithoutRef, CSSProperties, Ref} from 'react';
-import {Button} from 'components/Button';
+import type {CSSProperties, Ref} from 'react';
+import {Button, type ButtonPassthroughProps} from 'components/Button';
 import {chatScrollButtonRecipe} from 'components/Chat/ChatScrollButton.recipe';
 import {cx} from 'utils/cx';
 
-export interface ChatScrollButtonProps extends Omit<
-  ComponentPropsWithoutRef<'div'>,
-  'onClick'
-> {
+export interface ChatScrollButtonProps extends ButtonPassthroughProps {
   /**
    * Additional CSS class names applied to the root element.
    */
@@ -54,7 +51,7 @@ export function ChatScrollButton({
   onClick,
   ref,
   style,
-  ...rest
+  ...passthrough
 }: ChatScrollButtonProps): React.JSX.Element {
   const classes = chatScrollButtonRecipe({
     isExpanded: label != null,
@@ -63,13 +60,13 @@ export function ChatScrollButton({
 
   return (
     <div
-      {...rest}
       className={cx(classes.wrapper, className)}
       data-testid={dataTestId}
       ref={ref}
       style={style}>
       <div className={classes.pill}>
         <Button
+          {...passthrough}
           className={classes.button}
           icon={ChevronDown}
           isIconOnly={label == null}
diff --git a/src/components/Chat/ChatSendButton.tsx b/src/components/Chat/ChatSendButton.tsx
index 94884294..dd91e848 100644
--- a/src/components/Chat/ChatSendButton.tsx
+++ b/src/components/Chat/ChatSendButton.tsx
@@ -2,7 +2,7 @@
 
 import {ArrowUp, Square} from 'lucide-react';
 import type {CSSProperties, Ref} from 'react';
-import {Button} from 'components/Button';
+import {Button, type ButtonPassthroughProps} from 'components/Button';
 import {useChatComposerContext} from 'components/Chat/ChatContext';
 import type {IconComponent} from 'components/Icon';
 import {css} from 'styled-system/css';
@@ -13,7 +13,7 @@ const sendButtonStyle = css({
   flexShrink: 0,
 });
 
-export interface ChatSendButtonProps {
+export interface ChatSendButtonProps extends ButtonPassthroughProps {
   /**
    * Additional CSS class names applied to the button.
    */
@@ -85,6 +85,7 @@ export function ChatSendButton({
   size = 'md',
   stopIcon = Square,
   style,
+  ...passthrough
 }: ChatSendButtonProps): React.JSX.Element {
   const composer = useChatComposerContext();
   const showStop = isStopShown ?? composer?.isStopShown ?? false;
@@ -92,6 +93,7 @@ export function ChatSendButton({
 
   return (
     <Button
+      {...passthrough}
       className={cx(sendButtonStyle, className)}
       data-testid={dataTestId}
       icon={showStop ? stopIcon : sendIcon}
diff --git a/src/components/CopyButton/CopyButton.test.tsx b/src/components/CopyButton/CopyButton.test.tsx
index d6b9db9e..9ecd8a1b 100644
--- a/src/components/CopyButton/CopyButton.test.tsx
+++ b/src/components/CopyButton/CopyButton.test.tsx
@@ -249,4 +249,29 @@ describe('CopyButton', () => {
     await user.click(copyButton);
     expect(writeText).not.toHaveBeenCalled();
   });
+
+  it('forwards the shared button passthrough props', () => {
+    render(
+      <>
+        <span id="copy-hint">Copies the snippet</span>
+        <CopyButton
+          aria-describedby="copy-hint"
+          aria-keyshortcuts="Meta+C"
+          data-testid="copy-button"
+          id="copy"
+          value="copy me"
+        />
+      </>,
+    );
+
+    const copyButton = screen.getByTestId('copy-button');
+    expect(copyButton).toHaveAttribute('id', 'copy');
+    // The icon-only tooltip appends its own id, so the consumer's survives
+    // alongside it rather than replacing it.
+    expect(copyButton).toHaveAttribute(
+      'aria-describedby',
+      expect.stringContaining('copy-hint'),
+    );
+    expect(copyButton).toHaveAttribute('aria-keyshortcuts', 'Meta+C');
+  });
 });
diff --git a/src/components/CopyButton/CopyButton.tsx b/src/components/CopyButton/CopyButton.tsx
index 231391c6..7524ba41 100644
--- a/src/components/CopyButton/CopyButton.tsx
+++ b/src/components/CopyButton/CopyButton.tsx
@@ -2,19 +2,26 @@
 
 import {Check, Copy} from 'lucide-react';
 import {useCallback, useEffect, useRef, useState} from 'react';
-import {Button, type ButtonProps} from 'components/Button';
+import {
+  Button,
+  type ButtonPassthroughProps,
+  type ButtonProps,
+} from 'components/Button';
 import useAnnounce from 'hooks/useAnnounce';
 
-export interface CopyButtonProps extends Pick<
-  ButtonProps,
-  | 'className'
-  | 'data-testid'
-  | 'isDisabled'
-  | 'ref'
-  | 'size'
-  | 'style'
-  | 'variant'
-> {
+export interface CopyButtonProps
+  extends
+    ButtonPassthroughProps,
+    Pick<
+      ButtonProps,
+      | 'className'
+      | 'data-testid'
+      | 'isDisabled'
+      | 'ref'
+      | 'size'
+      | 'style'
+      | 'variant'
+    > {
   /**
    * Label and tooltip shown after a successful copy.
    * @default 'Copied'
@@ -67,6 +74,7 @@ export function CopyButton({
   style,
   value,
   variant = 'ghost',
+  ...passthrough
 }: CopyButtonProps): React.JSX.Element {
   const [isCopied, setIsCopied] = useState(false);
   const resetTimeoutRef = useRef<number | null>(null);
@@ -121,6 +129,7 @@ export function CopyButton({
   return (
     <>
       <Button
+        {...passthrough}
         className={className}
         data-testid={dataTestId}
         icon={isCopied ? Check : Copy}
diff --git a/src/components/SplitButton/SplitButton.test.tsx b/src/components/SplitButton/SplitButton.test.tsx
index df64c078..eaa93a0e 100644
--- a/src/components/SplitButton/SplitButton.test.tsx
+++ b/src/components/SplitButton/SplitButton.test.tsx
@@ -119,4 +119,27 @@ describe('SplitButton', () => {
       'silver-h_component.lg',
     );
   });
+
+  it('forwards the shared button passthrough props to the primary action', () => {
+    render(
+      <>
+        <span id="save-hint">Saves the document</span>
+        <SplitButton
+          aria-describedby="save-hint"
+          aria-keyshortcuts="Meta+S"
+          id="save"
+          items={[{label: 'Save a copy'}]}
+          label="Save"
+        />
+      </>,
+    );
+
+    const primary = screen.getByRole('button', {name: 'Save'});
+    expect(primary).toHaveAttribute('id', 'save');
+    expect(primary).toHaveAttribute('aria-describedby', 'save-hint');
+    expect(primary).toHaveAttribute('aria-keyshortcuts', 'Meta+S');
+    expect(
+      screen.getByRole('button', {name: 'More actions'}),
+    ).not.toHaveAttribute('id');
+  });
 });
diff --git a/src/components/SplitButton/SplitButton.tsx b/src/components/SplitButton/SplitButton.tsx
index d6b820dd..4f2d2747 100644
--- a/src/components/SplitButton/SplitButton.tsx
+++ b/src/components/SplitButton/SplitButton.tsx
@@ -2,7 +2,12 @@
 
 import {ChevronDown} from 'lucide-react';
 import type {CSSProperties, ReactNode, Ref} from 'react';
-import {Button, type ButtonProps, type ButtonSize} from 'components/Button';
+import {
+  Button,
+  type ButtonPassthroughProps,
+  type ButtonProps,
+  type ButtonSize,
+} from 'components/Button';
 import {ButtonGroup} from 'components/ButtonGroup';
 import {DropdownMenu, type DropdownMenuOption} from 'components/DropdownMenu';
 import type {IconComponent} from 'components/Icon';
@@ -13,10 +18,10 @@ import {useResolvedSize} from 'internal/SizeContext';
  * that opens a menu of related actions. A thin composition of `ButtonGroup`,
  * `Button`, and `DropdownMenu`.
  */
-export interface SplitButtonProps extends Pick<
-  ButtonProps,
-  'endContent' | 'isLoading' | 'onClick' | 'startContent'
-> {
+export interface SplitButtonProps
+  extends
+    ButtonPassthroughProps,
+    Pick<ButtonProps, 'endContent' | 'isLoading' | 'onClick' | 'startContent'> {
   /**
    * Compound menu content (`<DropdownMenuItem>`), an alternative to `items`.
    */
@@ -113,6 +118,7 @@ export function SplitButton({
   startContent,
   style,
   variant = 'secondary',
+  ...passthrough
 }: SplitButtonProps): React.JSX.Element {
   const size = useResolvedSize(sizeProp);
 
@@ -124,6 +130,7 @@ export function SplitButton({
       size={size}
       style={style}>
       <Button
+        {...passthrough}
         data-testid={dataTestId}
         endContent={endContent}
         icon={icon}
diff --git a/src/components/ToggleButton/ToggleButton.test.tsx b/src/components/ToggleButton/ToggleButton.test.tsx
index 31d10e51..31261a23 100644
--- a/src/components/ToggleButton/ToggleButton.test.tsx
+++ b/src/components/ToggleButton/ToggleButton.test.tsx
@@ -408,4 +408,26 @@ describe('ToggleButtonGroup', () => {
     expect(screen.getByTestId('btn-a')).toHaveClass('silver-h_component.sm');
     expect(screen.getByTestId('btn-b')).toHaveClass('silver-h_component.lg');
   });
+
+  it('forwards the shared button passthrough props', () => {
+    render(
+      <>
+        <span id="bold-hint">Bolds the selection</span>
+        <ToggleButton
+          aria-describedby="bold-hint"
+          aria-keyshortcuts="Meta+B"
+          data-testid="bold"
+          id="bold"
+          label="Bold"
+        />
+      </>,
+    );
+
+    const button = screen.getByTestId('bold');
+    expect(button).toHaveAttribute('id', 'bold');
+    expect(button).toHaveAttribute('aria-describedby', 'bold-hint');
+    expect(button).toHaveAttribute('aria-keyshortcuts', 'Meta+B');
+    // The component still owns the toggle contract it sets itself.
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+  });
 });
diff --git a/src/components/ToggleButton/ToggleButton.tsx b/src/components/ToggleButton/ToggleButton.tsx
index a3ea4984..0b14f139 100644
--- a/src/components/ToggleButton/ToggleButton.tsx
+++ b/src/components/ToggleButton/ToggleButton.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import type {CSSProperties, MouseEvent, Ref} from 'react';
-import type {ButtonSize} from 'components/Button';
+import type {ButtonPassthroughProps, ButtonSize} from 'components/Button';
 import {buttonRecipe} from 'components/Button/Button.recipe';
 import {Icon, type IconComponent} from 'components/Icon';
 import {Spinner} from 'components/Spinner';
@@ -11,7 +11,7 @@ import {Tooltip} from 'components/Tooltip';
 import {useResolvedSize} from 'internal/SizeContext';
 import {cx} from 'utils/cx';
 
-export interface ToggleButtonProps {
+export interface ToggleButtonProps extends ButtonPassthroughProps {
   /**
    * Additional CSS class names applied to the button root.
    */
@@ -101,6 +101,7 @@ export function ToggleButton({
   style,
   tooltip,
   value,
+  ...passthrough
 }: ToggleButtonProps): React.JSX.Element {
   const group = useToggleButtonGroup();
 
@@ -137,6 +138,7 @@ export function ToggleButton({
 
   const button = (
     <button
+      {...passthrough}
       aria-busy={isLoading || undefined}
       aria-label={isIconOnly || isLoading ? label : undefined}
       aria-pressed={isSelected}
diff --git a/src/index.ts b/src/index.ts
index 2307d193..90cd112b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,9 @@
-export {Button, type ButtonProps, type ButtonSize} from 'components/Button';
+export {
+  Button,
+  type ButtonPassthroughProps,
+  type ButtonProps,
+  type ButtonSize,
+} from 'components/Button';
 export {CopyButton, type CopyButtonProps} from 'components/CopyButton';
 export {
   ChatComposer,
diff --git a/src/internal/ActionElement.tsx b/src/internal/ActionElement.tsx
index 2e4d15a5..5697d16c 100644
--- a/src/internal/ActionElement.tsx
+++ b/src/internal/ActionElement.tsx
@@ -4,6 +4,7 @@
 import type {
   AriaAttributes,
   CSSProperties,
+  FocusEventHandler,
   KeyboardEventHandler,
   MouseEventHandler,
   ReactNode,
@@ -40,6 +41,7 @@ export interface ActionElementProps {
   isLink?: boolean;
   name?: string;
   onClick?: MouseEventHandler<HTMLElement>;
+  onFocus?: FocusEventHandler<HTMLElement>;
   onKeyDown?: KeyboardEventHandler<HTMLElement>;
   ref?: Ref<HTMLElement>;
   rel?: string;