@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Switch/Switch.doc.mjs

@@ -62,11 +62,17 @@ export const docs = {
       description: 'Whether the switch is disabled.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for the underlying checkbox input, useful for form submissions (submits "on" when the switch is on).',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -118,10 +124,10 @@ export const docs = {
     },
     {
       name: 'labelSpacing',
-      type: "'default' | 'spread'",
+      type: "'hug' | 'spread'",
       description:
-        'Spacing behavior between label and switch. "spread" pushes them to opposite ends of the container (full width).',
-      default: "'default'",
+        'Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width). "default" is a deprecated alias for "hug".',
+      default: "'hug'",
     },
   ],
   theming: {
@@ -203,11 +209,16 @@ export const docsZh = {
       description: '开关是否被禁用。',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description: '底层复选框输入的 HTML name 属性，用于表单提交（开启时提交 "on"）。',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -259,10 +270,10 @@ export const docsZh = {
     },
     {
       name: 'labelSpacing',
-      type: "'default' | 'spread'",
+      type: "'hug' | 'spread'",
       description:
-        '标签和开关之间的间距行为。"spread" 将它们推到容器的两端（全宽）。',
-      default: "'default'",
+        '标签和开关之间的间距行为。"hug" 将它们并排放置；"spread" 将它们推到容器的两端（全宽）。"default" 是 "hug" 的已弃用别名。',
+      default: "'hug'",
     },
   ],
   theming: {
@@ -309,6 +320,7 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label; still accessible to screen readers.',
     description: 'Description text below label.',
     isDisabled: 'Whether switch is disabled.',
+    htmlName: 'HTML name attr for the checkbox; submits "on" when on.',
     isOptional: 'Whether field is optional; mutually exclusive w/ isRequired.',
     isRequired: 'Whether switch is required; mutually exclusive w/ isOptional.',
     status: 'Status indicator w/ type + message; colored message box, sets aria-invalid on error.',
@@ -317,6 +329,6 @@ export const docsDense = {
     labelIcon: 'Icon before label text.',
     labelTooltip: 'Tooltip text in info icon at label end.',
     labelPosition: 'Which side label appears; "start" places before switch.',
-    labelSpacing: 'Spacing behavior; "spread" pushes to opposite ends (full width).',
+    labelSpacing: 'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width). "default" is deprecated alias for "hug".',
   },
 };

package/src/Switch/Switch.test.tsx

@@ -470,4 +470,141 @@ describe('Switch', () => {
       expect(screen.getByRole('switch')).toBeDisabled();
     });
   });
+  describe('labelSpacing', () => {
+    const getField = (container: HTMLElement) =>
+      container.querySelector<HTMLElement>('.astryx-switch-field')!;
+
+    it('omits the data attribute for the default hug spacing', () => {
+      const {container} = render(
+        <Switch label="Notify" value={false} onChange={() => {}} />,
+      );
+      expect(getField(container)).not.toHaveAttribute('data-label-spacing');
+    });
+
+    it('reflects spread spacing as a data attribute and variant class', () => {
+      const {container} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="spread"
+        />,
+      );
+      expect(getField(container)).toHaveAttribute(
+        'data-label-spacing',
+        'spread',
+      );
+      expect(getField(container).className).toContain('spread');
+    });
+
+    it('renders explicit hug the same as the default', () => {
+      const {container: implicit} = render(
+        <Switch label="Notify" value={false} onChange={() => {}} />,
+      );
+      const {container: explicit} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="hug"
+        />,
+      );
+      expect(getField(explicit)).not.toHaveAttribute('data-label-spacing');
+      expect(getField(explicit).className).toBe(getField(implicit).className);
+    });
+
+    it("treats the deprecated 'default' value as an alias for hug", () => {
+      const {container: hug} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="hug"
+        />,
+      );
+      const {container: deprecated} = render(
+        <Switch
+          label="Notify"
+          value={false}
+          onChange={() => {}}
+          labelSpacing="default"
+        />,
+      );
+      expect(getField(deprecated)).not.toHaveAttribute('data-label-spacing');
+      expect(getField(deprecated).className).toBe(getField(hug).className);
+      // The switch row keeps the hug layout, not the spread justification.
+      expect(getField(deprecated).firstElementChild?.className).toBe(
+        getField(hug).firstElementChild?.className,
+      );
+    });
+  });
+  describe('form participation', () => {
+    it('submits under htmlName when on', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={true}
+            onChange={() => {}}
+          />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('notify')).toBe('on');
+    });
+
+    it('is excluded from form data when disabled, even with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={true}
+            onChange={() => {}}
+            isDisabled
+            disabledMessage="Locked"
+          />
+        </form>,
+      );
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
+    });
+
+    it('submits nothing when off or when htmlName is omitted', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Off"
+            htmlName="off"
+            value={false}
+            onChange={() => {}}
+          />
+          <Switch label="Unnamed" value={true} onChange={() => {}} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect([...data.keys()]).toEqual([]);
+    });
+  });
+
+  describe('rest forwarding', () => {
+    it('forwards data-testid, id, and aria-* to the root element', () => {
+      const {container} = render(
+        <Switch
+          label="Notifications"
+          value={false}
+          onChange={() => {}}
+          data-testid="my-switch"
+          id="switch-1"
+          aria-label="Toggle notifications"
+        />,
+      );
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toBeNull();
+      expect(root).toHaveAttribute('id', 'switch-1');
+      expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
+    });
+  });
 });

package/src/Switch/Switch.tsx

@@ -185,7 +185,11 @@ const styles = stylex.create({
 
 export type SwitchLabelPosition = 'start' | 'end';
 
-export type SwitchLabelSpacing = 'default' | 'spread';
+export type SwitchLabelSpacing =
+  | 'hug'
+  | 'spread'
+  /** @deprecated Use `'hug'` instead. */
+  | 'default';
 
 export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
   /** Ref forwarded to the root element */
@@ -228,6 +232,13 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
    * @default false
    */
   isDisabled?: boolean;
+
+  /**
+   * The HTML name attribute for the underlying checkbox input.
+   * Useful for form submissions.
+   */
+  htmlName?: string;
+
   /**
    * Explains why the switch is disabled. When set together with `isDisabled`,
    * the switch shows a tooltip with this text on hover and keyboard focus, and
@@ -290,9 +301,11 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
   labelPosition?: SwitchLabelPosition;
   /**
    * Spacing behavior between label and switch.
-   * - 'default': Label and switch are positioned next to each other
+   * - 'hug': Label and switch are positioned next to each other
    * - 'spread': Label and switch are pushed to opposite ends
-   * @default 'default'
+   *
+   * 'default' is a deprecated alias for 'hug'.
+   * @default 'hug'
    */
   labelSpacing?: SwitchLabelSpacing;
   /**
@@ -334,6 +347,7 @@ export function Switch({
   isLoading = false,
   value,
   isDisabled = false,
+  htmlName,
   disabledMessage,
   isOptional = false,
   isRequired = false,
@@ -342,13 +356,14 @@ export function Switch({
   labelIcon,
   labelTooltip,
   labelPosition = 'end',
-  labelSpacing = 'default',
+  labelSpacing = 'hug',
   status,
   width,
   xstyle,
   className,
   style,
   ref,
+  ...rest
 }: SwitchProps) {
   const id = useId();
   const descriptionID = useId();
@@ -360,6 +375,10 @@ export function Switch({
 
   const isOn = optimisticValue === true;
 
+  // 'default' is a deprecated alias for 'hug' (#2889).
+  const resolvedLabelSpacing: SwitchLabelSpacing =
+    labelSpacing === 'default' ? 'hug' : labelSpacing;
+
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the switch row (which already exists) and the
   // native checkbox stays perceivable via aria-disabled instead of the disabled
@@ -395,6 +414,10 @@ export function Switch({
         id={id}
         type="checkbox"
         role="switch"
+        // Withhold the name while disabled: with a disabledMessage the
+        // input stays focusable (not natively disabled), and a disabled
+        // control must not submit.
+        name={isDisabled ? undefined : htmlName}
         checked={isOn}
         // With a disabledMessage the switch keeps focusability via aria-disabled
         // so the reason is focus-discoverable; toggling is still blocked by the
@@ -475,12 +498,14 @@ export function Switch({
       {...mergeProps(
         themeProps('switch-field', {
           labelPosition: labelPosition !== 'end' ? labelPosition : undefined,
-          labelSpacing: labelSpacing !== 'default' ? labelSpacing : undefined,
+          labelSpacing:
+            resolvedLabelSpacing !== 'hug' ? resolvedLabelSpacing : undefined,
         }),
         stylex.props(width != null && dynamicWidthStyles.width(width), xstyle),
         className,
         style,
-      )}>
+      )}
+      {...rest}>
       <div
         ref={el => {
           // Interaction (hover/focus) listeners for the disabled-message
@@ -493,7 +518,7 @@ export function Switch({
         }}
         {...stylex.props(
           styles.container,
-          labelSpacing === 'spread' && styles.containerSpread,
+          resolvedLabelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
         )}>
         {' '}

package/src/TabList/TabList.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -113,7 +113,7 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -135,7 +135,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },

package/src/TabList/TabList.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TabList} from './TabList';
 import {Tab} from './Tab';
@@ -702,3 +702,187 @@ describe('TabMenu', () => {
     expect(reportsItem).not.toHaveAttribute('aria-current');
   });
 });
+
+describe('TabMenu keyboard navigation (roving tabindex)', () => {
+  const menuOptions = [
+    {value: 'analytics', label: 'Analytics'},
+    {value: 'reports', label: 'Reports'},
+  ];
+
+  it('exposes the overflow menu as a single Tab stop (one item tabbable, rest -1)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    // Exactly one menu item is in the Tab sequence; arrow keys reach the rest.
+    expect(analytics).toHaveAttribute('tabindex', '0');
+    expect(reports).toHaveAttribute('tabindex', '-1');
+
+    const tabbable = [analytics, reports].filter(
+      el => el.getAttribute('tabindex') === '0',
+    );
+    expect(tabbable).toHaveLength(1);
+  });
+
+  it('moves focus between items with ArrowDown and ArrowUp', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(analytics).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(reports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('moves the roving tab stop with arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus analytics
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus reports
+
+    // The tab stop follows focus, so it is still a single stop after moving.
+    expect(reports).toHaveAttribute('tabindex', '0');
+    expect(analytics).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('jumps to first and last item with Home and End', async () => {
+    const user = userEvent.setup();
+    const options = [
+      {value: 'analytics', label: 'Analytics'},
+      {value: 'reports', label: 'Reports'},
+      {value: 'exports', label: 'Exports'},
+    ];
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={options} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const exports = screen.getByRole('menuitem', {
+      name: 'Exports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'End'});
+    expect(exports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'Home'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('selects an item with Enter and calls onChange', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <TabList value="home" onChange={handleChange}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    analytics.focus();
+    fireEvent.keyDown(analytics, {key: 'Enter'});
+
+    expect(handleChange).toHaveBeenCalledWith('analytics');
+  });
+
+  it('closes the menu when Tab is pressed inside it (APG menu-button)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+
+  it('closes the menu when Escape is pressed', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+});

package/src/TabList/TabMenu.tsx

@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
  */
 
-import React, {useCallback, useId, type ReactNode} from 'react';
+import React, {useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {renderIconSlot, type IconType} from '../Icon';
@@ -262,6 +262,7 @@ export function TabMenu({
 }: TabMenuProps) {
   const tabListCtx = useTabListContext();
   const menuId = useId();
+  const buttonRef = useRef<HTMLButtonElement>(null);
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -270,20 +271,50 @@ export function TabMenu({
     // The popup's own role="menu" is the exposed semantics; a modal dialog
     // wrapper would announce an unnamed dialog around the menu.
     role: 'none',
+    // Return focus to the trigger when the menu closes (Escape, Tab, select,
+    // or light dismiss) so keyboard focus is never dropped to <body>.
+    onHide: useCallback(() => {
+      buttonRef.current?.focus();
+    }, []),
   });
 
-  const {listRef, handleKeyDown: handleListKeyDown} =
-    useListFocus<HTMLDivElement>({
-      onEscape: () => popover.hide(),
-    });
+  // The overflow menu is a composite widget: a single roving tab stop with
+  // arrow-key navigation between items, per the APG menu pattern. The hook owns
+  // item tabindex — items render tabIndex={-1} and exactly one is promoted to 0.
+  const {
+    listRef,
+    handleKeyDown: handleListKeyDown,
+    handleFocus,
+    focusFirst,
+  } = useListFocus<HTMLDivElement>({
+    hasRovingTabIndex: true,
+    onEscape: () => popover.hide(),
+  });
 
   const handleToggle = useCallback(() => {
     if (popover.isOpen) {
       popover.hide();
     } else {
       popover.show();
+      // Move focus into the menu on open so arrow navigation works and the
+      // roving tab stop lands on a real item (APG menu-button focus-on-open).
+      requestAnimationFrame(() => focusFirst());
     }
-  }, [popover]);
+  }, [popover, focusFirst]);
+
+  const handleMenuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      // APG menu-button: Tab leaves the menu rather than walking its items.
+      // Close and let onHide return focus to the trigger, from which the
+      // browser's default Tab continues to the next element.
+      if (e.key === 'Tab') {
+        popover.hide();
+        return;
+      }
+      handleListKeyDown(e);
+    },
+    [handleListKeyDown, popover],
+  );
 
   const selectedOption = options.find(o => o.value === tabListCtx.value);
   const triggerLabel = selectedOption?.label ?? label;
@@ -299,7 +330,11 @@ export function TabMenu({
     [tabListCtx, popover],
   );
 
-  const setButtonRef = mergeRefs<HTMLButtonElement>(popover.triggerRef, ref);
+  const setButtonRef = mergeRefs<HTMLButtonElement>(
+    popover.triggerRef,
+    buttonRef,
+    ref,
+  );
 
   return (
     <>
@@ -357,7 +392,8 @@ export function TabMenu({
           id={menuId}
           role="menu"
           aria-label={label}
-          onKeyDown={handleListKeyDown}
+          onKeyDown={handleMenuKeyDown}
+          onFocus={handleFocus}
           {...mergeProps(
             themeProps('tab-menu-dropdown'),
             stylex.props(styles.dropdown),
@@ -371,7 +407,7 @@ export function TabMenu({
               <div
                 key={option.value}
                 role="menuitem"
-                tabIndex={0}
+                tabIndex={-1}
                 aria-current={isSelected ? 'true' : undefined}
                 onClick={() => handleSelect(option.value)}
                 onKeyDown={e => {