@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/Selector/Selector.tsx

@@ -42,6 +42,7 @@ import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerPlacement} from '../Layer/useLayer';
 import {Spinner} from '../Spinner';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {
   colorVars,
   sizeVars,
@@ -72,6 +73,7 @@ import {themeProps} from '../utils/themeProps';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {VisuallyHidden} from '../VisuallyHidden';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   // Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
@@ -524,8 +526,7 @@ type SelectorPropsClearable<T extends SelectorOptionType = SelectorOptionType> =
   };
 
 export type SelectorProps<T extends SelectorOptionType = SelectorOptionType> =
-  | SelectorPropsNonClearable<T>
-  | SelectorPropsClearable<T>;
+  SelectorPropsNonClearable<T> | SelectorPropsClearable<T>;
 
 /**
  * Default option renderer
@@ -536,6 +537,23 @@ function DefaultOption({option}: {option: SelectorOptionData}) {
   );
 }
 
+// Case-insensitive substring filter over the selectable options. Shared by the
+// `filteredItems` memo (rendering) and the search-change handler, which needs
+// the count for the *next* query synchronously to announce it exactly once per
+// keystroke rather than reacting to state in an effect.
+function filterOptionsByQuery(
+  items: SelectorOptionData[],
+  query: string,
+): SelectorOptionData[] {
+  if (!query) {
+    return items;
+  }
+  const q = query.toLowerCase();
+  return items.filter(item =>
+    (item.label ?? item.value).toLowerCase().includes(q),
+  );
+}
+
 /**
  * A selector/dropdown component for choosing from a list of options.
  *
@@ -553,6 +571,7 @@ function DefaultOption({option}: {option: SelectorOptionData}) {
 export function Selector<T extends SelectorOptionType>(
   props: SelectorProps<T>,
 ) {
+  const t = useTranslator();
   const {
     label,
     isLabelHidden = false,
@@ -566,7 +585,7 @@ export function Selector<T extends SelectorOptionType>(
     onChange,
     changeAction,
     isLoading = false,
-    placeholder = 'Select...',
+    placeholder: placeholderFromProps,
     size: sizeProp,
     status,
     labelTooltip,
@@ -574,7 +593,7 @@ export function Selector<T extends SelectorOptionType>(
     htmlName,
     renderOption,
     hasSearch = false,
-    searchPlaceholder = 'Search...',
+    searchPlaceholder: searchPlaceholderFromProps,
     placement,
     isDefaultOpen = false,
     'data-testid': testId,
@@ -585,6 +604,9 @@ export function Selector<T extends SelectorOptionType>(
     hasClear: hasClearProp,
     ...rest
   } = props as SelectorPropsClearable<T>;
+  const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
+  const searchPlaceholder =
+    searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
   const hasClear = hasClearProp === true;
   const size = useSize(sizeProp, 'md');
 
@@ -637,15 +659,10 @@ export function Selector<T extends SelectorOptionType>(
   );
 
   // Filter items by search query
-  const filteredItems = useMemo(() => {
-    if (!searchQuery) {
-      return selectableItems;
-    }
-    const query = searchQuery.toLowerCase();
-    return selectableItems.filter(item =>
-      (item.label ?? item.value).toLowerCase().includes(query),
-    );
-  }, [selectableItems, searchQuery]);
+  const filteredItems = useMemo(
+    () => filterOptionsByQuery(selectableItems, searchQuery),
+    [selectableItems, searchQuery],
+  );
 
   // Find selected item and its index for positioning
   const selectedItemIndex = useMemo(() => {
@@ -661,11 +678,20 @@ export function Selector<T extends SelectorOptionType>(
   // Ref for listbox to measure selected item position
   const listboxRef = useRef<HTMLDivElement>(null);
 
+  // Announce match counts / "No results found" politely as the user types, so
+  // screen-reader users hear how many options remain. Filtering was previously
+  // silent (comboboxes-7). Mirrors BaseTypeahead, which announces from its
+  // query-change callback (not a reactive effect) via the same useAnnounce hook.
+  const announce = useAnnounce();
+
   // Layer for dropdown positioning
   const handleLayerHide = useCallback(() => {
     setSearchQuery('');
+    // Clear any lingering result count when the popover closes so stale status
+    // text does not linger in the a11y tree.
+    announce('');
     triggerRef.current?.focus();
-  }, []);
+  }, [announce]);
 
   const popover = usePopover({
     onHide: handleLayerHide,
@@ -685,6 +711,29 @@ export function Selector<T extends SelectorOptionType>(
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
   }, []);
 
+  // Announce the filtered result count from the query-change handler (matching
+  // BaseTypeahead) rather than a reactive effect: computing the count for the
+  // next query here fires the announcement exactly once per keystroke and does
+  // not re-speak on unrelated re-renders.
+  const handleSearchChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const nextQuery = event.target.value;
+      setSearchQuery(nextQuery);
+      if (nextQuery.length === 0) {
+        // Emptying the query clears the region rather than announcing a count.
+        announce('');
+        return;
+      }
+      const count = filterOptionsByQuery(selectableItems, nextQuery).length;
+      announce(
+        count === 0
+          ? 'No results found'
+          : `${count} result${count === 1 ? '' : 's'}`,
+      );
+    },
+    [announce, selectableItems],
+  );
+
   // Calculate offset to position selected item over trigger. Explicit
   // placement opts out of the selector-specific overlay behavior and uses the
   // standard layer positioning API instead.
@@ -803,10 +852,10 @@ export function Selector<T extends SelectorOptionType>(
               ? getItemId(highlightedIndex)
               : undefined
           }
-          aria-label="Search options"
+          aria-label={t('@astryx.selector.searchOptions')}
           type="text"
           value={searchQuery}
-          onChange={e => setSearchQuery(e.target.value)}
+          onChange={handleSearchChange}
           onKeyDown={e => {
             // Arrow keys navigate options; Enter selects; Escape/Tab close.
             // Home/End are left to the input for caret movement.
@@ -831,10 +880,12 @@ export function Selector<T extends SelectorOptionType>(
     listboxId,
     searchQuery,
     searchPlaceholder,
+    handleSearchChange,
     onKeyDown,
     popover.isOpen,
     highlightedIndex,
     getItemId,
+    t,
   ]);
 
   // Render an individual item
@@ -1014,7 +1065,7 @@ export function Selector<T extends SelectorOptionType>(
           <button
             type="button"
             onClick={handleClear}
-            aria-label={`Clear ${label}`}
+            aria-label={t('@astryx.selector.clearLabel', {label})}
             {...stylex.props(styles.clearButton)}>
             <Icon icon="close" size="sm" color="secondary" />
           </button>

package/src/Selector/SelectorOption.doc.mjs

@@ -20,7 +20,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon displayed before the label. See `npx astryx docs icons` for valid semantic names.',
+        'Icon displayed before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'description',

package/src/SideNav/SideNav.tsx

@@ -45,6 +45,7 @@ import {useResizable} from '../Resizable/useResizable';
 import type {ResizableConfig} from '../Resizable/useResizable';
 import {ResizeHandle} from '../Resizable/ResizeHandle';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Constants
@@ -330,6 +331,7 @@ export function SideNav({
   handleRef,
   ...props
 }: SideNavProps) {
+  const t = useTranslator();
   // Parse collapsible prop
   const collapsibleConfig = typeof collapsible === 'object' ? collapsible : {};
   const isCollapsible = !!collapsible;
@@ -504,7 +506,7 @@ export function SideNav({
     <nav
       ref={mergeRefs(ref, navRef)}
       role="navigation"
-      aria-label="Side navigation"
+      aria-label={t('@astryx.sideNav.label')}
       data-testid={testId}
       {...mergeProps(
         themeProps('side-nav'),
@@ -569,7 +571,7 @@ export function SideNav({
         pillPlacement="end"
         isAlwaysVisible={false}
         resizable={resizableHook.props}
-        label="Resize sidebar"
+        label={t('@astryx.sideNav.resizeSidebar')}
       />
     </div>
   ) : (

package/src/SideNav/SideNavCollapseButton.tsx

@@ -30,6 +30,7 @@ import {
   type SideNavImperativeCollapseHandle,
 } from './SideNavCollapseContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -105,6 +106,7 @@ export function SideNavCollapseButton({
   onClick: onClickProp,
   ...props
 }: SideNavCollapseButtonProps) {
+  const t = useTranslator();
   const {isCollapsed, toggle, isCollapsible} =
     useSideNavCollapseState(handleRef);
   const {isMobile} = useAppShellMobile();
@@ -118,7 +120,7 @@ export function SideNavCollapseButton({
   return (
     <Button
       ref={ref}
-      label={label ?? (isCollapsed ? 'Expand sidebar' : 'Collapse sidebar')}
+      label={label ?? (isCollapsed ? t('@astryx.sideNavCollapseButton.expandSidebar') : t('@astryx.sideNavCollapseButton.collapseSidebar'))}
       variant="ghost"
       {...props}
       onClick={composeEventHandlers(onClickProp, toggle)}

package/src/SideNav/SideNavHeading.tsx

@@ -44,6 +44,7 @@ import type {BaseProps} from '../BaseProps';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -342,13 +343,14 @@ export function SideNavHeading({
   ref,
   ...props
 }: SideNavHeadingProps) {
+  const t = useTranslator();
   const LinkComponent = useLinkComponent(as);
   const {isCollapsed} = useSideNavCollapse();
   const rootRef = useRef<HTMLDivElement>(null);
   const collapsedItemRef = useRef<HTMLElement>(null);
 
   const popover = usePopover({
-    dialogLabel: 'Navigation menu',
+    dialogLabel: t('@astryx.sideNav.heading.dialogLabel'),
     hasCloseButton: false,
   });
 
@@ -603,7 +605,7 @@ export function SideNavHeading({
           {renderTextContent(
             <button
               type="button"
-              aria-label="Open menu"
+              aria-label={t('@astryx.sideNav.heading.openMenu')}
               onClick={e => {
                 e.stopPropagation();
                 triggerProps.onClick();
@@ -665,7 +667,7 @@ export function SideNavHeading({
             showChevron ? (
               <button
                 type="button"
-                aria-label="Open menu"
+                aria-label={t('@astryx.sideNav.heading.openMenu')}
                 onClick={e => {
                   e.stopPropagation();
                   triggerProps.onClick();

package/src/SideNav/SideNavItem.doc.mjs

@@ -23,12 +23,12 @@ export const docs = {
     {
       name: 'icon',
       type: 'IconType',
-      description: 'Icon displayed in the outline (unselected) variant. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed in the outline (unselected) variant. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'selectedIcon',
       type: 'IconType',
-      description: 'Icon displayed when the item is selected (filled variant). See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed when the item is selected (filled variant). See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isSelected',

package/src/SideNav/SideNavItem.tsx

@@ -54,6 +54,7 @@ import {getIcon} from '../Icon/globalIconRegistry';
 import {useSideNavRenderMode} from './SideNavRenderContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -356,6 +357,7 @@ export function SideNavItem({
   'data-testid': testId,
   ref,
 }: SideNavItemProps) {
+  const t = useTranslator();
   const {isCollapsed} = useSideNavCollapse();
   const renderMode = useSideNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
@@ -626,7 +628,7 @@ export function SideNavItem({
         <button
           type="button"
           onClick={handleToggleClick}
-          aria-label={isItemCollapsed ? `Expand ${label}` : `Collapse ${label}`}
+          aria-label={isItemCollapsed ? t('@astryx.sideNavItem.expand', {label}) : t('@astryx.sideNavItem.collapse', {label})}
           aria-expanded={!isItemCollapsed}
           aria-controls={`${id}-children`}
           {...stylex.props(styles.expandToggle)}>

package/src/Slider/Slider.doc.mjs

@@ -132,7 +132,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         'Status indicator object (`{ type, message }`) for validation feedback.',
     },
@@ -286,7 +286,7 @@ export const docsZh = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         '验证反馈的状态指示器对象（`{ type, message }`）。',
     },

package/src/Stack/Stack.doc.mjs

@@ -24,25 +24,25 @@ export const docs = {
       props: [
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
         },
         {
           name: 'padding',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
         },
         {
           name: 'paddingInline',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
         },
         {
           name: 'paddingBlock',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
         },
@@ -127,25 +127,25 @@ export const docs = {
       props: [
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
         },
         {
           name: 'padding',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
         },
         {
           name: 'paddingInline',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
         },
         {
           name: 'paddingBlock',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
         },
@@ -289,7 +289,7 @@ export const docsZh = {
       props: [
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             '间距步进（数字字面量）：0、0.5、1、1.5、2、3、4、5、6、8、10。在 JSX 中使用数字表达式 e.g. gap={4}，不要使用字符串 gap="4"。',
         },
@@ -358,7 +358,7 @@ export const docsZh = {
       props: [
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description:
             '间距步进（数字字面量）：0、0.5、1、1.5、2、3、4、5、6、8、10。在 JSX 中使用数字表达式 e.g. gap={4}，不要使用字符串 gap="4"。',
         },

package/src/Switch/Switch.doc.mjs

@@ -90,7 +90,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         'Status indicator with type and message. Displays a colored message box below the switch and sets aria-invalid when type is "error".',
     },
@@ -107,7 +107,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon displayed before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',
@@ -236,7 +236,7 @@ export const docsZh = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         '带类型和消息的状态指示器。在开关下方显示彩色消息框，当类型为 "error" 时设置 aria-invalid。',
     },

package/src/Switch/Switch.test.tsx

@@ -197,6 +197,22 @@ describe('Switch', () => {
     expect(screen.getByLabelText('Toggle row')).toBeInTheDocument();
   });
 
+  it('keeps description linked via aria-describedby when isLabelHidden', () => {
+    render(
+      <Switch
+        label="Toggle row"
+        isLabelHidden
+        description="Enables sync for this row"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const switchEl = screen.getByRole('switch');
+    const description = screen.getByText('Enables sync for this row');
+    expect(description.id).not.toBe('');
+    expect(switchEl.getAttribute('aria-describedby')).toContain(description.id);
+  });
+
   it('shows label visually by default', () => {
     render(
       <Switch label="Enable notifications" value={false} onChange={() => {}} />,

package/src/Switch/Switch.tsx

@@ -393,9 +393,11 @@ export function Switch({
   });
 
   // Build aria-describedby from description and status message
-  // Only include descriptionID when the element actually renders
+  // Only include descriptionID when the element actually renders.
+  // FieldLabel renders the description (with descriptionID) even when the
+  // label is visually hidden — it's sr-only, so keep it linked.
   const describedByParts: string[] = [];
-  if (description && !isLabelHidden) {
+  if (description) {
     describedByParts.push(descriptionID);
   }
   if (status?.message) {

package/src/TabList/Tab.tsx

@@ -138,7 +138,11 @@ const styles = stylex.create({
   },
   indicator: {
     position: 'absolute',
-    bottom: '-1px',
+    // Sits on the tab's bottom edge by default (-1px). When the tab strip
+    // reserves space for a divider rail — TabList `hasDivider` or a Toolbar
+    // with a bottom divider — that ancestor sets `--_tab-indicator-bottom`
+    // to drop the indicator onto the rail beneath the reserved gap.
+    bottom: 'var(--_tab-indicator-bottom, -1px)',
     left: spacingVars['--spacing-3'],
     right: spacingVars['--spacing-3'],
     height: '2px',

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\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm) — the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { 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\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm) — the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { 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\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm) — the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { 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

@@ -323,6 +323,72 @@ describe('TabList', () => {
   });
 });
 
+describe('TabList divider gap', () => {
+  // The divider adds the reserved gap + indicator offset via a single class
+  // (StyleX applies deterministic classes in the test env). Capture that
+  // class set once so the assertions describe intent, not opaque hashes.
+  function navClasses(hasDivider: boolean): Set<string> {
+    const {unmount} = render(
+      <TabList value="home" onChange={() => {}} hasDivider={hasDivider}>
+        <Tab value="home" label="Home" />
+      </TabList>,
+    );
+    const nav = screen.getByRole('navigation');
+    const classes = new Set(nav.className.split(/\s+/).filter(Boolean));
+    unmount();
+    return classes;
+  }
+
+  it('adds divider-only styling classes when hasDivider is set', () => {
+    const withDivider = navClasses(true);
+    const withoutDivider = navClasses(false);
+
+    // Every class the plain nav has must still be present when divided: the
+    // divider only adds styling (border + reserved gap + indicator offset),
+    // it never removes the base nav styles.
+    for (const cls of withoutDivider) {
+      expect(withDivider.has(cls)).toBe(true);
+    }
+
+    // And it must add at least one class the undivided nav does not have.
+    const added = [...withDivider].filter(c => !withoutDivider.has(c));
+    expect(added.length).toBeGreaterThan(0);
+  });
+
+  it('does not add divider styling to an undivided tab list (default)', () => {
+    // Default (no hasDivider) and explicit hasDivider={false} are identical:
+    // the non-divided path is untouched by the divider gap change.
+    expect(navClasses(false)).toEqual(
+      (() => {
+        const {unmount} = render(
+          <TabList value="home" onChange={() => {}}>
+            <Tab value="home" label="Home" />
+          </TabList>,
+        );
+        const nav = screen.getByRole('navigation');
+        const classes = new Set(nav.className.split(/\s+/).filter(Boolean));
+        unmount();
+        return classes;
+      })(),
+    );
+  });
+
+  it('keeps the selected indicator rendered under a divider', () => {
+    render(
+      <TabList value="home" onChange={() => {}} hasDivider>
+        <Tab value="home" label="Home" />
+        <Tab value="away" label="Away" />
+      </TabList>,
+    );
+    const selected = screen.getByRole('button', {name: 'Home'});
+    // The indicator span carries the selected marker; the divider must not
+    // drop it (it is repositioned onto the rail, not removed).
+    expect(
+      selected.querySelector('[data-selected="selected"]'),
+    ).toBeInTheDocument();
+  });
+});
+
 describe('TabList keyboard navigation (roving tabindex)', () => {
   it('exposes the tab strip as a single Tab stop (only selected tab is tabbable)', () => {
     render(

package/src/TabList/TabList.tsx

@@ -29,6 +29,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 /**
  * Selector matching the focusable stops in the tab strip: every Tab
@@ -95,6 +96,14 @@ const styles = stylex.create({
     borderBottomWidth: borderVars['--border-width'],
     borderBottomStyle: 'solid',
     borderBottomColor: colorVars['--color-border'],
+    // Reserve a gap between the tabs and the divider rail so the hover pill
+    // (which fills the tab height) no longer touches the underline, and an
+    // adjacent same-size Button aligns to the tabs rather than butting the
+    // rail. The tabs keep their element-size height; this padding grows the
+    // strip. `--_tab-indicator-bottom` drops the selected indicator through
+    // the reserved gap (+ the 1px border) so it still sits on the rail.
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    '--_tab-indicator-bottom': `calc(-1 * (${spacingVars['--spacing-1']} + ${borderVars['--border-width']}))`,
   },
 });
 
@@ -129,11 +138,13 @@ export function TabList({
   onKeyDown: onKeyDownProp,
   onFocus: onFocusProp,
   onBlur: onBlurProp,
-  'aria-label': ariaLabel = 'Tabs',
+  'aria-label': ariaLabelFromProps,
   'aria-orientation': _ariaOrientation,
   [EDGE_COMP_ATTR]: _edgeCompAttr,
   ...restProps
 }: TabListProps) {
+  const t = useTranslator();
+  const ariaLabel = ariaLabelFromProps ?? t('@astryx.tabList.label');
   const size = useSize(sizeProp, 'md');
 
   // Roving-tabindex keyboard navigation across the tab strip via the shared