@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Button/Button.test.tsx

@@ -151,6 +151,19 @@ describe('Button', () => {
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement));
   });
 
+  it('keeps its merged ref attached across unrelated rerenders', () => {
+    const ref = vi.fn();
+    const {rerender} = render(<Button label="Test" ref={ref} />);
+    const button = screen.getByRole('button');
+    expect(ref).toHaveBeenLastCalledWith(button);
+    ref.mockClear();
+
+    rerender(<Button label="Test" variant="primary" ref={ref} />);
+
+    expect(ref).not.toHaveBeenCalled();
+    expect(screen.getByRole('button')).toBe(button);
+  });
+
   // endContent tests
   it('renders endContent after label', () => {
     render(
@@ -463,6 +476,21 @@ describe('Button', () => {
   });
 
   describe('elevation', () => {
+    it('reflects each elevation level as a theme attribute', () => {
+      const attrFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Button label="Save" elevation={elevation} />,
+        );
+        return container
+          .querySelector('button')!
+          .getAttribute('data-elevation');
+      };
+      expect(attrFor('none')).toBe('none');
+      expect(attrFor('low')).toBe('low');
+      expect(attrFor('med')).toBe('med');
+      expect(attrFor('high')).toBe('high');
+    });
+
     it('renders a distinct class for each elevation level', () => {
       const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
         const {container} = render(
@@ -480,13 +508,13 @@ describe('Button', () => {
     });
 
     it('defaults to flat (elevation none)', () => {
-      const {container: def} = render(<Button label="Save" />);
+      const {container} = render(<Button label="Save" />);
+      const button = container.querySelector('button')!;
+      expect(button).toHaveAttribute('data-elevation', 'none');
       const {container: none} = render(
         <Button label="Save" elevation="none" />,
       );
-      expect(def.querySelector('button')!.className).toBe(
-        none.querySelector('button')!.className,
-      );
+      expect(button.className).toBe(none.querySelector('button')!.className);
     });
   });
 

package/src/Button/Button.tsx

@@ -42,7 +42,8 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
@@ -688,7 +689,13 @@ export function Button({
   );
 
   const sharedMergedProps = mergeProps(
-    themeProps('button', {variant, size}),
+    // Inside a group the group owns the surface's elevation, so the button
+    // reflects the tier it actually paints rather than the prop it was handed.
+    themeProps('button', {
+      variant,
+      size,
+      elevation: buttonGroup ? 'none' : elevation,
+    }),
     sharedStylexProps,
     className,
     style,
@@ -757,9 +764,9 @@ export function Button({
       : null;
 
   // Merge the consumer ref with the tooltip hook's trigger ref so both point at
-  // the same element. mergeRefs tolerates undefined, so this is a no-op for the
-  // tooltip side when no tooltip is set.
-  const mergedButtonRef = mergeRefs(
+  // the same element. useMergedRefs tolerates undefined, so this is a no-op for
+  // the tooltip side when no tooltip is set.
+  const mergedButtonRef = useMergedRefs(
     ref,
     tooltip != null ? tooltipHook.ref : undefined,
   );

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-button-group', visualProps: ['size', 'orientation']},
+      {className: 'astryx-button-group', visualProps: ['size', 'orientation', 'elevation']},
     ],
   },
   components: [
@@ -46,6 +46,9 @@ export const docs = {
       {guidance: false, description: "Don't mix wildly different actions. A Save button next to a Delete button in the same group is confusing."},
       {guidance: false, description: "Don't use ButtonGroup for navigation. Use SegmentedControl or TabList for switching between views."},
       {guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},
+      {guidance: true, description: 'Name the group for what its buttons act on. The label is the group\'s accessible name and a screen reader reads it before each member.'},
+      {guidance: true, description: 'Keep the group a single Tab stop. Arrow keys move between members along the orientation, Home/End jump to the ends, and disabled members are skipped. This is the WAI-ARIA APG roving tabindex technique: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
+      {guidance: false, description: "Don't disable the group to show that an action is in flight. A disabled member drops focus, so a keyboard user loses their place; leave the group enabled and show progress on the button that started the work."},
     ],
     anatomy: [
       {name: 'Button', required: true, description: 'One or more Button or IconButton children that form the connected group.'},
@@ -84,6 +87,9 @@ export const docsZh = {
       {guidance: false, description: '不要混合差异很大的操作，将保存按钮和删除按钮放在同一组中会令人困惑。'},
       {guidance: false, description: '不要使用 ButtonGroup 进行导航，使用 SegmentedControl 或 TabList 切换视图。'},
       {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组，请并排放置并留有间隔。'},
+      {guidance: true, description: '按钮组的标签应说明这些按钮作用于什么。该标签是按钮组的无障碍名称，屏幕阅读器会在每个成员之前朗读它。'},
+      {guidance: true, description: '按钮组是单个 Tab 停靠点。方向键沿排列方向在成员间移动焦点，Home/End 跳到首尾，禁用成员会被跳过——即 WAI-ARIA APG 的 roving tabindex 技术。'},
+      {guidance: false, description: '不要用禁用整个按钮组来表示操作进行中。禁用的成员会失去焦点，键盘用户会丢失位置；请保持按钮组可用，并在发起操作的按钮上显示进度。'},
     ],
     anatomy: [
       {name: '按钮', required: true, description: '一个或多个 Button 或 IconButton 子元素，形成连接的组。'},
@@ -105,6 +111,9 @@ export const docsDense = {
       {guidance: false, description: "Don't mix unrelated actions in one group."},
       {guidance: false, description: "Don't use for navigation. Use SegmentedControl or TabList."},
       {guidance: false, description: "Don't nest ButtonGroups."},
+      {guidance: true, description: 'Label the group for what its buttons act on; it is the accessible name.'},
+      {guidance: true, description: 'Single Tab stop; arrows move between members, Home/End to ends, disabled skipped (APG roving tabindex).'},
+      {guidance: false, description: "Don't disable the group for an in-flight action; a disabled member drops focus."},
     ],
   },
   components: [

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -12,7 +12,9 @@
  */
 
 import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import type {ReactNode} from 'react';
+import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {transformSync} from '@babel/core';
 import stylexBabelPlugin from '@stylexjs/babel-plugin';
 import {readFileSync} from 'node:fs';
@@ -611,5 +613,406 @@ describe('ButtonGroup', () => {
         none.querySelector('[role="group"]')!.className,
       );
     });
+
+    it('exposes the elevation to a theme as a data attribute', () => {
+      render(
+        <ButtonGroup label="Actions" elevation="high">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+
+      expect(screen.getByRole('group')).toHaveAttribute(
+        'data-elevation',
+        'high',
+      );
+    });
+
+    it('reports flat on a member, since the group owns the surface', () => {
+      render(
+        <ButtonGroup label="Actions" elevation="high">
+          <Button label="One" elevation="high" />
+        </ButtonGroup>,
+      );
+
+      expect(screen.getByRole('button', {name: 'One'})).toHaveAttribute(
+        'data-elevation',
+        'none',
+      );
+    });
+  });
+
+  // ===========================================================================
+  // Keyboard navigation
+  //
+  // The group wires useListFocus, so arrow keys move focus between members.
+  // The last two tests cover the boundary: a member can own a layer, whose
+  // keys belong to that layer, and the group itself can sit inside a layer,
+  // whose keys are still the group's own. Both must hold at once.
+  // ===========================================================================
+  describe('keyboard navigation', () => {
+    const clipboard = (
+      <ButtonGroup label="Actions">
+        <Button label="Copy" />
+        <Button label="Cut" />
+        <Button label="Paste" />
+      </ButtonGroup>
+    );
+
+    it('moves focus between members with the arrow keys, wrapping at the end', async () => {
+      const user = userEvent.setup();
+      render(clipboard);
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowRight}{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+
+      await user.keyboard('{ArrowLeft}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+    });
+
+    it('jumps to the first and last member with Home and End', async () => {
+      const user = userEvent.setup();
+      render(clipboard);
+
+      screen.getByRole('button', {name: 'Cut'}).focus();
+
+      await user.keyboard('{End}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+
+      await user.keyboard('{Home}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('uses the vertical arrows when the group is vertical', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Actions" orientation="vertical">
+          <Button label="Copy" />
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowDown}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowUp}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('follows visual direction in RTL', async () => {
+      const user = userEvent.setup();
+      // dir sits on the group because jsdom resolves computed direction from
+      // the element's own attribute, not from an ancestor.
+      render(
+        <ButtonGroup label="Actions" dir="rtl">
+          <Button label="Copy" />
+          <Button label="Cut" />
+          <Button label="Paste" />
+        </ButtonGroup>,
+      );
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowLeft}');
+      expect(screen.getByRole('button', {name: 'Cut'})).toHaveFocus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+    });
+
+    it('skips a disabled member', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" />
+          <Button label="Cut" isDisabled />
+          <Button label="Paste" />
+        </ButtonGroup>,
+      );
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+    });
+
+    it('leaves arrow keys to a member\u2019s open menu', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Approve action">
+          <Button label="Allow once" />
+          <DropdownMenu
+            hasChevron={false}
+            button={{label: 'Allow options', isIconOnly: true}}
+            items={[{label: 'Allow for 30 minutes'}, {label: 'Always allow'}]}
+          />
+        </ButtonGroup>,
+      );
+
+      await user.click(screen.getByRole('button', {name: /Allow options/}));
+      const item = screen.getByRole('menuitem', {
+        name: 'Allow for 30 minutes',
+        hidden: true,
+      });
+      item.focus();
+
+      // Assert positively: the menu item keeps focus. `.not.toHaveFocus()` on
+      // the group's buttons would also pass if the group had thrown focus
+      // somewhere else entirely.
+      fireEvent.keyDown(item, {key: 'ArrowRight'});
+      expect(item).toHaveFocus();
+
+      fireEvent.keyDown(item, {key: 'ArrowLeft'});
+      expect(item).toHaveFocus();
+
+      // End belongs to the menu's own list focus, so it lands on the last menu
+      // item rather than the group's last button.
+      fireEvent.keyDown(item, {key: 'End'});
+      expect(
+        screen.getByRole('menuitem', {name: 'Always allow', hidden: true}),
+      ).toHaveFocus();
+    });
+
+    it('leaves a link member in the arrow order', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Docs actions">
+          <Button label="Save" />
+          <Button label="Docs" href="https://example.com" />
+          <Button label="Print" />
+        </ButtonGroup>,
+      );
+
+      screen.getByRole('button', {name: 'Save'}).focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('link', {name: 'Docs'})).toHaveFocus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', {name: 'Print'})).toHaveFocus();
+    });
+
+    it('still moves between its own members when the group sits inside a popover', async () => {
+      const user = userEvent.setup();
+      // A group rendered inside a Popover, ContextMenu, HoverCard or Toast has
+      // a `[popover]` ancestor, because that is how useLayer mounts a layer.
+      // A bare `popover` div is the same DOM fact without the layer harness.
+      render(
+        <div popover="manual">
+          <ButtonGroup label="Actions">
+            <Button label="Copy" />
+            <Button label="Cut" />
+            <Button label="Paste" />
+          </ButtonGroup>
+        </div>,
+      );
+
+      // A closed popover is display:none in jsdom, so its contents read as
+      // inaccessible; focus and key handling still work on them.
+      const button = (name: string) =>
+        screen.getByRole('button', {name, hidden: true});
+
+      button('Copy').focus();
+
+      await user.keyboard('{ArrowRight}');
+      expect(button('Cut')).toHaveFocus();
+
+      await user.keyboard('{End}');
+      expect(button('Paste')).toHaveFocus();
+
+      await user.keyboard('{Home}');
+      expect(button('Copy')).toHaveFocus();
+    });
+  });
+
+  // ===========================================================================
+  // Roving tabindex
+  //
+  // The group is a single tab stop: exactly one enabled member carries
+  // tabindex="0", the rest carry -1, and the stop moves with arrow navigation.
+  // Entering and leaving is asserted through the real tab order as well as the
+  // attribute, because the attribute alone says nothing about a member the
+  // itemSelector missed — such a member stays natively tabbable and quietly
+  // adds a second stop.
+  // ===========================================================================
+  describe('roving tabindex', () => {
+    const tabIndexOf = (name: string) =>
+      screen.getByRole('button', {name}).getAttribute('tabindex');
+
+    const bracketed = (group: ReactNode) => (
+      <>
+        <button type="button">before</button>
+        {group}
+        <button type="button">after</button>
+      </>
+    );
+
+    const clipboard = (
+      <ButtonGroup label="Actions">
+        <Button label="Copy" />
+        <Button label="Cut" />
+        <Button label="Paste" />
+      </ButtonGroup>
+    );
+
+    it('gives the group one tab stop, on the first member', () => {
+      render(clipboard);
+
+      expect(tabIndexOf('Copy')).toBe('0');
+      expect(tabIndexOf('Cut')).toBe('-1');
+      expect(tabIndexOf('Paste')).toBe('-1');
+    });
+
+    it('takes one Tab to enter and one to leave', async () => {
+      const user = userEvent.setup();
+      render(bracketed(clipboard));
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'before'})).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'after'})).toHaveFocus();
+    });
+
+    it('moves the tab stop with arrow navigation', async () => {
+      const user = userEvent.setup();
+      render(clipboard);
+
+      screen.getByRole('button', {name: 'Copy'}).focus();
+      await user.keyboard('{ArrowRight}');
+
+      expect(tabIndexOf('Copy')).toBe('-1');
+      expect(tabIndexOf('Cut')).toBe('0');
+    });
+
+    it('never parks the tab stop on a disabled member', () => {
+      render(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" isDisabled />
+          <Button label="Cut" />
+          <Button label="Paste" />
+        </ButtonGroup>,
+      );
+
+      expect(tabIndexOf('Copy')).toBe('-1');
+      expect(tabIndexOf('Cut')).toBe('0');
+    });
+
+    it('repairs the tab stop when the member holding it unmounts', () => {
+      const {rerender} = render(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" />
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+      expect(tabIndexOf('Copy')).toBe('0');
+
+      rerender(
+        <ButtonGroup label="Actions">
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+
+      expect(tabIndexOf('Cut')).toBe('0');
+    });
+
+    it('repairs the tab stop when the member holding it becomes disabled', () => {
+      const {rerender} = render(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" />
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+      expect(tabIndexOf('Copy')).toBe('0');
+
+      rerender(
+        <ButtonGroup label="Actions">
+          <Button label="Copy" isDisabled />
+          <Button label="Cut" />
+        </ButtonGroup>,
+      );
+
+      expect(tabIndexOf('Copy')).toBe('-1');
+      expect(tabIndexOf('Cut')).toBe('0');
+    });
+
+    it('counts a link member as the tab stop', async () => {
+      const user = userEvent.setup();
+      render(
+        bracketed(
+          <ButtonGroup label="Docs actions">
+            <Button label="Docs" href="https://example.com" />
+            <Button label="Print" />
+          </ButtonGroup>,
+        ),
+      );
+
+      expect(
+        screen.getByRole('link', {name: 'Docs'}).getAttribute('tabindex'),
+      ).toBe('0');
+      expect(tabIndexOf('Print')).toBe('-1');
+
+      await user.tab();
+      await user.tab();
+      expect(screen.getByRole('link', {name: 'Docs'})).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'after'})).toHaveFocus();
+    });
+
+    it('contributes no tab stop when the whole group is disabled', async () => {
+      const user = userEvent.setup();
+      render(
+        bracketed(
+          <ButtonGroup label="Actions" isDisabled>
+            <Button label="Copy" />
+            <Button label="Cut" />
+          </ButtonGroup>,
+        ),
+      );
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'before'})).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'after'})).toHaveFocus();
+    });
+
+    it('leaves the tab stop on its own members when a member owns an open menu', async () => {
+      const user = userEvent.setup();
+      render(
+        <ButtonGroup label="Approve action">
+          <Button label="Allow once" />
+          <DropdownMenu
+            hasChevron={false}
+            button={{label: 'Allow options', isIconOnly: true}}
+            items={[{label: 'Allow for 30 minutes'}, {label: 'Always allow'}]}
+          />
+        </ButtonGroup>,
+      );
+
+      const trigger = screen.getByRole('button', {name: /Allow options/});
+      expect(tabIndexOf('Allow once')).toBe('0');
+      expect(trigger.getAttribute('tabindex')).toBe('-1');
+
+      await user.click(trigger);
+
+      // The menu's own items are a different list level (the boundary), so the
+      // group must not stamp them or hand them its tab stop.
+      const item = screen.getByRole('menuitem', {
+        name: 'Allow for 30 minutes',
+        hidden: true,
+      });
+      expect(item.getAttribute('tabindex')).not.toBe('0');
+      expect(tabIndexOf('Allow once')).toBe('0');
+    });
   });
 });

package/src/ButtonGroup/ButtonGroup.tsx

@@ -28,12 +28,13 @@ import {radiusVars, shadowVars} from '../theme/tokens.stylex';
 import type {Elevation} from '../utils/types';
 import {SizeProvider, useSize} from '../SizeContext/SizeContext';
 import {useListFocus} from '../hooks/useListFocus';
-import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {ButtonGroupContext} from './ButtonGroupContext';
 import type {ButtonGroupOrientation} from './ButtonGroupContext';
 import {themeProps} from '../utils/themeProps';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Props
 // =============================================================================
@@ -130,6 +131,10 @@ const elevationStyles = stylex.create({
  * Children automatically detect the group via context and apply position-aware
  * styles in pure CSS.
  *
+ * The group is a single tab stop: arrow keys move between members along the
+ * orientation, Home/End jump to the ends, focus wraps, and disabled members are
+ * skipped (the APG roving tabindex technique, via `useListFocus`).
+ *
  * Members that render their own layer — a Button with a `tooltip`, or a
  * DropdownMenu — compose correctly, including as the trailing member.
  *
@@ -166,13 +171,25 @@ export function ButtonGroup({
   ref,
   'data-testid': testId,
   onKeyDown,
+  onFocus,
   ...props
 }: ButtonGroupProps): ReactNode {
   const size = useSize(sizeProp, 'md');
 
-  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
-    itemSelector: 'button, [tabindex="0"]',
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    // Roving rewrites `tabindex` on every item, so the selector cannot key off
+    // a value: `[tabindex="0"]` would drop each member the moment it is
+    // stamped -1. `a[href]` catches a Button rendered with `href`.
+    itemSelector: 'button, a[href], [tabindex]',
+    // A member's layer renders inline inside the group (useLayer does not
+    // portal it), so a key pressed in an open DropdownMenu bubbles here. The
+    // boundary is the group's own root or any layer, whichever is nearer to
+    // the target. Naming the group's own root is what keeps a group rendered
+    // inside a Popover or Toast working: bailing on any [popover] ancestor
+    // instead would swallow every arrow key it owns.
+    boundarySelector: '[role="group"], [popover]',
     orientation,
+    hasRovingTabIndex: true,
   });
 
   const contextValue = useMemo(
@@ -184,10 +201,10 @@ export function ButtonGroup({
     <ButtonGroupContext value={contextValue}>
       <SizeProvider value={size}>
         <div
-          ref={mergeRefs(ref, listRef)}
+          ref={useMergedRefs(ref, listRef)}
           {...props}
           {...mergeProps(
-            themeProps('button-group', {size, orientation}),
+            themeProps('button-group', {size, orientation, elevation}),
             stylex.props(
               styles.group,
               orientation === 'vertical' && styles.vertical,
@@ -200,6 +217,7 @@ export function ButtonGroup({
           role="group"
           aria-label={label}
           onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
+          onFocus={composeEventHandlers(onFocus, handleFocus)}
           aria-disabled={isDisabled || undefined}
           data-testid={testId}>
           {children}

package/src/Calendar/Calendar.doc.mjs

@@ -83,7 +83,8 @@ export const docs = {
     {
       name: 'focusDate',
       type: 'ISODateString',
-      description: 'Controlled visible month.',
+      description:
+        'Controlled visible month. Unset, the calendar opens on the selected date, else on today clamped into the min/max window.',
     },
     {
       name: 'onFocusDateChange',
@@ -156,7 +157,7 @@ export const docsZh = {
     {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},
     {name: 'maxRangeSpan', type: 'number', description: '范围模式：范围最多可跨越的天数，含首尾两端（7 = 7 天窗口）。选定起始日后限制窗口大小。'},
     {name: 'minRangeSpan', type: 'number', description: '范围模式：范围最少需跨越的天数，含首尾两端（2 表示禁止单日范围）。默认为 1。'},
-    {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。'},
+    {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。未设置时，日历打开时显示已选日期所在月份；若无选中值，则显示今天，并将其限制在 min/max 范围内。'},
     {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},
     {name: 'handleRef', type: 'React.Ref<CalendarHandle>', description: '日历导航的命令式句柄，包括 navigateTo()。'},
     {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},
@@ -221,7 +222,7 @@ export const docsDense = {
     dateConstraints: 'custom constraint fns',
     maxRangeSpan: 'range mode: max days a range may span, both ends counted (7 = 7-day window)',
     minRangeSpan: 'range mode: min days a range must span, both ends counted (default 1)',
-    focusDate: 'controlled visible month',
+    focusDate: 'controlled visible month (default: selected date, else today clamped into min/max)',
     onFocusDateChange: 'navigation callback',
     handleRef: 'imperative navigation handle',
     hasOutsideDays: 'show days from adjacent months',