@astryxdesign/core 0.4.6 → 0.4.7-canary.29be96d

package/src/BottomSheet/BottomSheetEdgeTint.test.tsx

@@ -0,0 +1,225 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetEdgeTint.test.tsx
+ * @input Uses vitest, @testing-library/react, BottomSheet, BottomSheetSwitcher
+ * @output Tests which sheets carry the iOS Safari bottom edge tint, and pins
+ *   the declarations WebKit's edge sampler reads
+ * @position Core testing; validates BottomSheetEdgeTint.tsx and its two hosts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render} from '@testing-library/react';
+import {BottomSheet} from './BottomSheet';
+import {BottomSheetSwitcher} from './BottomSheetSwitcher';
+
+// jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = vi.fn();
+    Element.prototype.releasePointerCapture = vi.fn();
+  }
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+  vi.stubGlobal(
+    'requestAnimationFrame',
+    vi.fn((callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    }),
+  );
+  vi.stubGlobal('cancelAnimationFrame', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function tints(): ReadonlyArray<Element> {
+  return Array.from(document.querySelectorAll('[data-sheet-edge-tint]'));
+}
+
+async function edgeTintSource(): Promise<string> {
+  const tint = (await fullSource()).match(/\n {2}tint: \{([\s\S]*?)\n {2}\},/);
+  expect(tint).not.toBeNull();
+  return tint![1];
+}
+
+/** The tint's declarations with its explanatory comments stripped out. */
+async function edgeTintDeclarations(): Promise<string> {
+  return (await edgeTintSource())
+    .split('\n')
+    .filter(line => !line.trim().startsWith('//'))
+    .join('\n');
+}
+
+async function fullSource(): Promise<string> {
+  const fs = await import('fs');
+  const path = await import('path');
+  return fs.readFileSync(
+    path.resolve(__dirname, './BottomSheetEdgeTint.tsx'),
+    'utf-8',
+  );
+}
+
+describe('BottomSheetEdgeTint', () => {
+  it('gives a non-modal sheet an edge tint to colour the iOS toolbar strip', () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  // A modal sheet's ::backdrop is a case WebKit's sampler handles on its own,
+  // so a second sampling target there would only fight it.
+  it('leaves a modal sheet to its ::backdrop', () => {
+    render(
+      <BottomSheet isOpen onOpenChange={() => {}} label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('renders the tint inside the dialog, so it unmounts with the sheet', () => {
+    const {rerender} = render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.closest('dialog')).not.toBeNull();
+
+    rerender(<div />);
+    expect(tints()).toHaveLength(0);
+  });
+
+  // The switcher owns one shared dialog for the whole flow, so the tint
+  // belongs to that dialog and must not be minted per child sheet.
+  it('gives a non-modal switcher flow exactly one tint', () => {
+    render(
+      <BottomSheetSwitcher
+        activeSheet="comment"
+        hasScrim={false}
+        onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+        <BottomSheet sheetId="confirmation" label="Confirmation">
+          Confirmation
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  it('leaves a modal switcher flow to its ::backdrop', () => {
+    render(
+      <BottomSheetSwitcher activeSheet="comment" onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('keeps the tint out of the accessibility tree and out of hit testing', async () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.getAttribute('aria-hidden')).toBe('true');
+    expect(tint?.textContent).toBe('');
+    expect(await edgeTintSource()).toContain("pointerEvents: 'none'");
+  });
+
+  // Every declaration below is load-bearing for a heuristic that lives in
+  // WebKit, not in this repo, and none of it is observable in jsdom or in any
+  // engine without retractable browser chrome — so it is asserted on the style
+  // definition, the way BottomSheetPanel pins its handle gradient.
+  describe('the declarations WebKit samples', () => {
+    it('is fixed and flush with the bottom edge of the viewport', async () => {
+      const tint = await edgeTintSource();
+      // Only a fixed or sticky box is a candidate, and only a box flush with
+      // the edge is the one Safari hit tests.
+      expect(tint).toContain("position: 'fixed'");
+      expect(tint).toContain('insetBlockEnd: 0');
+      expect(tint).toContain('insetInline: 0');
+    });
+
+    it('clears the 10px floor below which WebKit ignores the declared colour', async () => {
+      const height = (await fullSource()).match(
+        /const SAMPLE_HEIGHT_PX = (\d+);/,
+      );
+      expect(height).not.toBeNull();
+      expect(Number(height![1])).toBeGreaterThan(10);
+      expect(await edgeTintSource()).toContain(
+        'height: `${SAMPLE_HEIGHT_PX}px`',
+      );
+    });
+
+    it('declares the sheet surface colour, so the strip matches the sheet', async () => {
+      expect(await edgeTintSource()).toContain(
+        "backgroundColor: colorVars['--color-background-surface']",
+      );
+    });
+
+    // visibility: hidden, display: none and a low opacity all disqualify the
+    // element from sampling. A mask does not, which is the only reason the
+    // strip can be both readable by Safari and invisible to the user.
+    it('hides itself with a mask rather than with visibility or opacity', async () => {
+      const tint = await edgeTintDeclarations();
+      expect(tint).toContain(
+        "maskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).toContain(
+        "WebkitMaskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).not.toContain('visibility');
+      expect(tint).not.toContain('opacity');
+      expect(tint).not.toContain("display: 'none'");
+    });
+  });
+});

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetEdgeTint.tsx
+ * @input Uses StyleX and core color tokens
+ * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @position Private helper rendered inside a non-modal BottomSheet dialog
+ *
+ * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
+ * colour it paints behind its translucent toolbars by sampling the page: it
+ * hit tests a point just inside each viewport edge, walks up to the nearest
+ * `fixed`/`sticky` ancestor, and extends that element's declared
+ * `background-color` into the browser chrome.
+ *
+ * A modal sheet is served by that heuristic already — WebKit has a dedicated
+ * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
+ * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
+ * which is transparent and viewport-sized, and WebKit answers a viewport-sized
+ * candidate by *keeping the colour it already had* — the host page's. The page
+ * then shows through behind the address bar while the sheet covers the screen
+ * above it.
+ *
+ * This element gives the heuristic something unambiguous to sample: fixed,
+ * full width, flush with the bottom edge, taller than WebKit's 10px minimum
+ * for reading a declared colour, and painted in the sheet's own surface
+ * colour. It is masked out so it never renders for the user; Safari reads the
+ * computed style, not the painted pixels.
+ *
+ * Everywhere else it is inert decoration.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+/**
+ * WebKit ignores the declared `background-color` of a sampled box thinner than
+ * 10px and falls back to sampling painted pixels, which a masked element has
+ * none of. 12px clears that floor with room to spare and is still far below
+ * the ~40px of chrome it colours.
+ */
+const SAMPLE_HEIGHT_PX = 12;
+
+const styles = stylex.create({
+  tint: {
+    position: 'fixed',
+    insetInline: 0,
+    insetBlockEnd: 0,
+    height: `${SAMPLE_HEIGHT_PX}px`,
+    backgroundColor: colorVars['--color-background-surface'],
+    // Above the panel so the edge hit test lands here, and never in the way of
+    // a touch that was meant for the sheet.
+    zIndex: 2,
+    pointerEvents: 'none',
+    // Invisible to the user. WebKit's sampler checks `visibility` and
+    // `opacity` — either would disqualify the element — but not `mask`, so
+    // this hides the strip while leaving the colour readable. Without it the
+    // strip would show as a hairline under the panel as the sheet slides out.
+    maskImage: 'linear-gradient(transparent, transparent)',
+    WebkitMaskImage: 'linear-gradient(transparent, transparent)',
+  },
+});
+
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export function BottomSheetEdgeTint() {
+  return (
+    <div
+      {...stylex.props(styles.tint)}
+      data-sheet-edge-tint=""
+      aria-hidden="true"
+    />
+  );
+}

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -328,4 +328,70 @@ describe('BottomSheetPanel', () => {
       "backgroundColor: colorVars['--color-background-surface']",
     );
   });
+
+  /**
+   * The exit is not the entrance played backwards.
+   *
+   * `--ease-standard` is a decelerate curve: on it the sheet was half gone in
+   * 59ms of a 410ms transition and 90% gone in 163ms, so the close was over
+   * before it could be seen. The closing state therefore carries its own
+   * accelerating curve, and only the closing state does.
+   */
+  it('closes on an accelerating curve of its own, not the entrance timing', () => {
+    const declarationsFor = (element: HTMLElement) => {
+      const classes = new Set(element.className.split(/\s+/));
+      const out: string[] = [];
+      for (const styleSheet of Array.from(document.styleSheets)) {
+        let rules: CSSRuleList;
+        try {
+          rules = styleSheet.cssRules;
+        } catch {
+          continue;
+        }
+        for (const rule of Array.from(rules)) {
+          const selector = (rule as CSSStyleRule).selectorText;
+          const owner = selector?.match(/^\.([\w-]+)/)?.[1];
+          if (owner != null && classes.has(owner)) {
+            out.push(rule.cssText);
+          }
+        }
+      }
+      return out.join('\n');
+    };
+
+    const {container: closing} = render(
+      <BottomSheetPanel
+        state={{kind: 'exiting'}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const closingRules = declarationsFor(
+      closing.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    // An accelerating curve: no vertical rise at the start (y1 = 0), so the
+    // travel lands inside the duration instead of ahead of it.
+    expect(closingRules).toContain(
+      'transition-timing-function: cubic-bezier(.3,0,.6,.6)',
+    );
+
+    const {container: resting} = render(
+      <BottomSheetPanel
+        state={{kind: 'open', entering: false}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const restingRules = declarationsFor(
+      resting.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    expect(restingRules).toContain(
+      'transition-timing-function: var(--ease-standard)',
+    );
+    expect(restingRules).not.toContain('cubic-bezier(.3,0,.6,.6)');
+  });
 });

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -149,8 +149,27 @@ const styles = stylex.create({
       transitionDuration: '0.01s',
     },
   },
+  /**
+   * The exit is its own motion, not the entrance played backwards.
+   *
+   * `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve:
+   * it spends its speed immediately and coasts. That is right for an entrance,
+   * where the sheet arrives fast and settles, and wrong for an exit. Measured
+   * on device, it put the sheet half off-screen in 59ms of a 410ms close and
+   * 90% off in 163ms -- the travel is over before the eye has followed it, and
+   * the rest of the duration moves pixels already below the fold.
+   *
+   * An exit accelerates instead: away from rest, gathering speed, quickest as
+   * it leaves the screen. The curve is deliberately gentle rather than a hard
+   * `ease-in` -- it is moving within ~50ms, so the close reads as one
+   * departure rather than a hesitation and a snap. The duration is the
+   * entrance's own band, so only the curve differs between the two
+   * directions; a shorter band leaves too little visible travel once a theme
+   * scales the motion scale down (neutral's medium is 300ms against 410ms).
+   */
   sheetClosing: {
     transform: 'translateY(100%)',
+    transitionTimingFunction: 'cubic-bezier(0.3, 0, 0.6, 0.6)',
   },
   sheetFading: {
     opacity: 0,

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -22,6 +22,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
@@ -51,6 +52,7 @@ import {
   useScrollLock,
 } from '../hooks';
 import {composeEventHandlers, mergeProps, mergeRefs} from '../utils';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -103,6 +105,14 @@ const styles = stylex.create({
       },
     },
   },
+  // The flow's dim leaves with its last panel. Same rule, same reasoning, as
+  // a standalone sheet's -- see `scrimClosing` in BottomSheet.tsx. A handoff
+  // between two sheets is not a close, and keeps the entrance curve.
+  scrimClosing: {
+    '::backdrop': {
+      transitionTimingFunction: 'linear',
+    },
+  },
 });
 
 type RetainedSheetPhase = 'covered' | 'aligning' | 'fading' | 'exiting';
@@ -593,6 +603,7 @@ export function BottomSheetSwitcher({
     styles.dialog,
     isFlowVisible && styles.dialogOpen,
     hasScrim && styles.scrim,
+    hasScrim && isFlowVisible && activeSheet == null && styles.scrimClosing,
     !hasScrim && styles.dialogNonModal,
     xstyle,
   );
@@ -620,6 +631,8 @@ export function BottomSheetSwitcher({
           ? {role: 'alertdialog'}
           : undefined)}>
         {children}
+        {/* A modal flow's ::backdrop already answers Safari's edge sampler. */}
+        {hasScrim ? null : <BottomSheetEdgeTint />}
       </dialog>
     </BottomSheetSwitcherContext>
   );

package/src/BottomSheet/useSheetGestures.test.ts

@@ -530,6 +530,33 @@ describe('useSheetGestures', () => {
       expect(hook.result.current.dragOffset).toBe(40);
     });
 
+    /**
+     * A finger is never still. Tapping a control inside the sheet drifts a
+     * pixel or two, and with no slop that drift promoted to a sheet drag —
+     * which wrote `transition: none` onto the panel across the release, so the
+     * close the tap triggered cut instead of animating. That is the "the sheet
+     * closes with no animation" report: only on a tap, and only on a tap
+     * inside the sheet (the scrim never arms a drag).
+     */
+    it('treats a few pixels of finger drift as a tap, not a drag', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0); // at the top, where a pull-down would promote
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 3, 40, body); // the drift of a finger tapping a button
+      expect(hook.result.current.isDragging).toBe(false);
+      // and nothing suppressed the panel's transition, so a close that lands
+      // now still animates
+      expect(hook.result.current.contentProps.style.transition).toBeUndefined();
+    });
+
+    it('still promotes once the pull passes the tap slop', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0);
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 9, 40, body); // just past the 8px slop
+      expect(hook.result.current.isDragging).toBe(true);
+    });
+
     it('does not hijack scrolling when the body is scrolled down', () => {
       const {hook} = setup({snapHeights: () => [200]});
       const body = makeBody(120); // scrolled, not at the top

package/src/BottomSheet/useSheetGestures.ts

@@ -118,6 +118,20 @@ const OVERSCROLL_MAX = 48;
 // the scroll, large enough that a swipe merely coming to rest on the last pixel
 // doesn't start a drag on jitter.
 const CONTENT_END_HANDOFF_SLOP = 4;
+// How far a finger resting on the body must travel before the pull becomes a
+// sheet drag rather than a tap.
+//
+// This used to be zero: any downward movement promoted. A finger is never
+// still, so tapping a control inside the sheet drifted a pixel or two and
+// started a drag -- which suppresses the panel's transition, correctly, for as
+// long as the sheet is tracking the finger. The close that the tap triggered
+// then landed inside that window and cut instead of animating. A deliberate
+// pull was unaffected; only a tap, and only a tap inside the sheet, since the
+// scrim is outside the body and arms nothing.
+//
+// 8px is the conventional tap slop, a shade over iOS's own recognizer, and
+// well under what a real pull covers in its first frames.
+const DRAG_PROMOTION_SLOP = 8;
 
 // Short haptic tick on detent settle where supported. iOS Safari doesn't
 // expose navigator.vibrate, so this is a no-op there; skipped under
@@ -1140,7 +1154,7 @@ export function useSheetGestures({
         return;
       }
       const delta = event.clientY - armed.startCoord;
-      if (delta > 0 && armed.scroller.scrollTop <= 0) {
+      if (delta > DRAG_PROMOTION_SLOP && armed.scroller.scrollTop <= 0) {
         // Downward pull at the top: promote to a sheet drag, anchored at the
         // original pointer-down position so the pull distance carries over.
         armedBodyRef.current = null;
@@ -1302,8 +1316,10 @@ export function useSheetGestures({
       // no longer scroll that way: at the top, a downward pull (delta > 0)
       // collapses; at the bottom, an upward pull (delta < 0) expands. The
       // opposite direction is a real scroll, so disarm and let it through.
-      const pullDownAtTop = armed.top && delta > 0 && atTop(scroller);
-      const pullUpAtBottom = armed.bottom && delta < 0 && atBottom(scroller);
+      const pullDownAtTop =
+        armed.top && delta > DRAG_PROMOTION_SLOP && atTop(scroller);
+      const pullUpAtBottom =
+        armed.bottom && delta < -DRAG_PROMOTION_SLOP && atBottom(scroller);
       if (pullDownAtTop || pullUpAtBottom) {
         event.preventDefault();
         touchDragRef.current = null;
@@ -1433,15 +1449,19 @@ export function useSheetGestures({
       style: {
         transform:
           activeOffset !== 0 ? `translateY(${activeOffset}px)` : undefined,
+        // Gated on the sheet being up: suppression must not outlive the sheet
+        // it was suppressing for. The host swaps the panel to its closing
+        // state in whatever frame the dismissal lands, and a stale `none`
+        // would apply to that transform too, cutting the exit.
         transition:
-          isDragging || isScrollAreaReconciling || reducedMotion
+          isOpen && (isDragging || isScrollAreaReconciling || reducedMotion)
             ? 'none'
             : undefined,
         touchAction: 'none',
         overscrollBehavior: 'contain',
       },
     }),
-    [activeOffset, isDragging, isScrollAreaReconciling, reducedMotion],
+    [activeOffset, isDragging, isOpen, isScrollAreaReconciling, reducedMotion],
   );
 
   const handleProps = useMemo<SheetHandleProps>(

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -38,6 +38,7 @@ import {
   spacingVars,
   typeScaleVars,
   radiusVars,
+  fontWeightVars,
 } from '../theme/tokens.stylex';
 import {BreadcrumbContext, type BreadcrumbsVariant} from './Breadcrumbs';
 import {useLinkComponent} from '../Link/useLinkComponent';
@@ -186,7 +187,7 @@ const itemStyles = stylex.create({
     color: colorVars['--color-text-secondary'],
   },
   current: {
-    fontWeight: 'inherit',
+    fontWeight: fontWeightVars['--font-weight-semibold'],
   },
   defaultCurrent: {
     color: colorVars['--color-text-primary'],

package/src/Button/Button.doc.mjs

@@ -150,6 +150,28 @@ export const docs = {
       description:
         'Async click handler. Shows loading state while the returned promise is pending.',
     },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When provided, renders the button as a link element (<a> or custom link component).',
+    },
+    {
+      name: 'as',
+      type: 'ComponentType',
+      description:
+        'Custom link component to use when href is provided (e.g. Next.js Link).',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description: 'HTML target attribute when rendered as a link (e.g. "_blank").',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description: 'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+    },
   ],
   playground: {
     defaults: {

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',