@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

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,8 @@ 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\u2019s accessible name and a screen reader reads it before each member.'},
+      {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 +86,8 @@ export const docsZh = {
       {guidance: false, description: '不要混合差异很大的操作，将保存按钮和删除按钮放在同一组中会令人困惑。'},
       {guidance: false, description: '不要使用 ButtonGroup 进行导航，使用 SegmentedControl 或 TabList 切换视图。'},
       {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组，请并排放置并留有间隔。'},
+      {guidance: true, description: '按钮组的标签应说明这些按钮作用于什么。该标签是按钮组的无障碍名称，屏幕阅读器会在每个成员之前朗读它。'},
+      {guidance: false, description: '不要用禁用整个按钮组来表示操作进行中。禁用的成员会失去焦点，键盘用户会丢失位置；请保持按钮组可用，并在发起操作的按钮上显示进度。'},
     ],
     anatomy: [
       {name: '按钮', required: true, description: '一个或多个 Button 或 IconButton 子元素，形成连接的组。'},
@@ -105,6 +109,8 @@ 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: 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,8 @@
  */
 
 import {describe, it, expect} 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 {transformSync} from '@babel/core';
 import stylexBabelPlugin from '@stylexjs/babel-plugin';
 import {readFileSync} from 'node:fs';
@@ -611,5 +612,188 @@ 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',
+      );
+    });
+  });
+
+  // ===========================================================================
+  // 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('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();
+    });
   });
 });

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
 // =============================================================================
@@ -172,6 +173,13 @@ export function ButtonGroup({
 
   const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
     itemSelector: 'button, [tabindex="0"]',
+    // 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,
   });
 
@@ -184,10 +192,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,

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

package/src/Calendar/Calendar.test.tsx

@@ -263,6 +263,58 @@ describe('Calendar', () => {
     expect(day15).not.toBeDisabled();
   });
 
+  // ─── Initial Visible Month ───────────────────────────────────
+
+  describe('opens on a month inside the min/max window', () => {
+    beforeEach(() => {
+      vi.useFakeTimers({toFake: ['Date']});
+      vi.setSystemTime(new Date(2026, 7, 21, 12, 0, 0));
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('opens on today when today is inside the window', () => {
+      render(<Calendar min="2026-01-01" max="2026-12-31" />);
+
+      expect(screen.getByText('August 2026')).toBeInTheDocument();
+    });
+
+    it('opens on min when the window is entirely in the future', () => {
+      render(<Calendar min="2027-03-04" max="2027-06-30" />);
+
+      expect(screen.getByText('March 2027')).toBeInTheDocument();
+      expect(getDayButton(4, 'March', 2027)).not.toBeDisabled();
+    });
+
+    it('opens on max when the window is entirely in the past', () => {
+      render(<Calendar min="2019-01-01" max="2019-04-30" />);
+
+      expect(screen.getByText('April 2019')).toBeInTheDocument();
+      expect(getDayButton(30, 'April', 2019)).not.toBeDisabled();
+    });
+
+    it('keeps max in the last pane in the two-month layout', () => {
+      render(<Calendar numberOfMonths={2} min="2019-01-01" max="2019-04-30" />);
+
+      expect(screen.getByText('March 2019 – April 2019')).toBeInTheDocument();
+    });
+
+    it('still honors an explicit focusDate outside the window', () => {
+      render(
+        <Calendar focusDate="2026-01-01" min="2027-03-04" max="2027-06-30" />,
+      );
+
+      expect(screen.getByText('January 2026')).toBeInTheDocument();
+    });
+
+    it('still opens on the selected value outside the window', () => {
+      render(<Calendar defaultValue="2031-07-04" min="2019-01-01" />);
+
+      expect(screen.getByText('July 2031')).toBeInTheDocument();
+    });
+  });
+
   it('respects custom dateConstraints', () => {
     // Only allow weekdays
     const isWeekday = (date: Date) => {

package/src/Calendar/Calendar.tsx

@@ -11,6 +11,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Calendar/Calendar.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Calendar/getInitialFocusDate.ts (which month the calendar opens on)
  * - /packages/core/src/Calendar/Calendar.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Calendar/index.ts (exports if types change)
  * - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)
@@ -60,6 +61,7 @@ import {
 } from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {getInitialFocusDate} from './getInitialFocusDate';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -142,7 +144,9 @@ interface CalendarBaseProps extends Omit<
 
   /**
    * Controlled focus date (which month is visible).
-   * If not provided, defaults to selected date or today.
+   * If not provided, defaults to the selected date, else today clamped into
+   * the `min`/`max` window (so a window that excludes today opens on the
+   * bound nearest to it, not on an all-disabled month).
    */
   focusDate?: ISODateString;
 
@@ -277,20 +281,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // Determine effective value
   const effectiveValue = value !== undefined ? value : internalValue;
 
-  // Focus date state (which month is visible)
-  const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() => {
-    if (focusDateProp) {
-      return plainDateFromISO(focusDateProp);
-    }
-    if (effectiveValue) {
-      if (typeof effectiveValue === 'string') {
-        return plainDateFromISO(effectiveValue);
-      } else {
-        return plainDateFromISO(effectiveValue.start);
-      }
-    }
-    return plainDateToday();
-  });
+  // Focus date state (which month is visible). Falls back to today, clamped
+  // into the min/max window so a window that doesn't contain today doesn't
+  // open on an all-disabled month.
+  const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() =>
+    getInitialFocusDate({
+      focusDate: focusDateProp,
+      value: effectiveValue,
+      min,
+      max,
+      numberOfMonths,
+      today,
+    }),
+  );
 
   // Use controlled focusDate if callback is provided, otherwise use internal state
   const isControlledFocus =

package/src/Calendar/getInitialFocusDate.test.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getInitialFocusDate.test.ts
+ * @input Uses vitest
+ * @output Test suite for getInitialFocusDate
+ * @position Tests for getInitialFocusDate.ts
+ *
+ * SYNC: When getInitialFocusDate.ts changes, update tests accordingly
+ */
+
+import {describe, it, expect} from 'vitest';
+import {getInitialFocusDate} from './getInitialFocusDate';
+import {plainDateFromISO, plainDateToISO} from '../utils/plainDate';
+
+const TODAY = plainDateFromISO('2026-08-21');
+
+function focusISO(options: Partial<Parameters<typeof getInitialFocusDate>[0]>) {
+  return plainDateToISO(
+    getInitialFocusDate({numberOfMonths: 1, today: TODAY, ...options}),
+  );
+}
+
+describe('getInitialFocusDate', () => {
+  it('opens on today when there are no bounds', () => {
+    expect(focusISO({})).toBe('2026-08-21');
+  });
+
+  it('opens on today when today is inside the min/max window', () => {
+    expect(focusISO({min: '2026-01-01', max: '2026-12-31'})).toBe('2026-08-21');
+  });
+
+  it('treats the bounds as inclusive', () => {
+    expect(focusISO({min: '2026-08-21'})).toBe('2026-08-21');
+    expect(focusISO({max: '2026-08-21'})).toBe('2026-08-21');
+  });
+
+  it('opens on min when the whole window is in the future', () => {
+    expect(focusISO({min: '2027-03-04', max: '2027-06-30'})).toBe('2027-03-04');
+  });
+
+  it('opens on max when the whole window is in the past', () => {
+    expect(focusISO({min: '2019-01-01', max: '2019-04-30'})).toBe('2019-04-01');
+  });
+
+  it('clamps against a one-sided min', () => {
+    expect(focusISO({min: '2030-05-17'})).toBe('2030-05-17');
+  });
+
+  it('clamps against a one-sided max', () => {
+    expect(focusISO({max: '2020-02-09'})).toBe('2020-02-01');
+  });
+
+  it('lands max in the last pane in the two-month layout', () => {
+    // Opening on max's month would spend the second pane entirely
+    // out of bounds, so the window's end sits on the right instead.
+    expect(focusISO({max: '2020-02-09', numberOfMonths: 2})).toBe('2020-01-01');
+  });
+
+  it('does not shift the two-month layout back past min', () => {
+    expect(
+      focusISO({min: '2020-02-03', max: '2020-02-09', numberOfMonths: 2}),
+    ).toBe('2020-02-03');
+  });
+
+  it('prefers the selected value over the bounds', () => {
+    expect(focusISO({value: '2031-07-04', min: '2019-01-01'})).toBe(
+      '2031-07-04',
+    );
+  });
+
+  it('uses a range value start as the visible month', () => {
+    expect(focusISO({value: {start: '2019-03-08', end: '2019-03-19'}})).toBe(
+      '2019-03-08',
+    );
+  });
+
+  it('prefers an explicit focusDate over everything else', () => {
+    expect(
+      focusISO({
+        focusDate: '2015-11-02',
+        value: '2031-07-04',
+        min: '2026-01-01',
+        max: '2026-12-31',
+      }),
+    ).toBe('2015-11-02');
+  });
+
+  it('prefers min when the bounds are inverted', () => {
+    // Degenerate input (min after max) — resolve it deterministically
+    // rather than reading the second bound off a contradiction.
+    expect(focusISO({min: '2027-01-01', max: '2020-01-01'})).toBe('2027-01-01');
+  });
+});

package/src/Calendar/getInitialFocusDate.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getInitialFocusDate.ts
+ * @input PlainDate utilities, min/max bounds, today
+ * @output Exports getInitialFocusDate — the month Calendar opens on
+ * @position Calendar-specific helper; used by Calendar.tsx
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/getInitialFocusDate.test.ts
+ * - /packages/core/src/Calendar/Calendar.tsx (the only caller)
+ */
+
+import type {ISODateString, DateRange} from '../utils/dateTypes';
+import {
+  type PlainDate,
+  plainDateFromISO,
+  plainDateSetFirstOfMonth,
+  plainDateAddMonths,
+  plainDateIsBefore,
+  plainDateIsAfter,
+} from '../utils/plainDate';
+
+export interface InitialFocusDateOptions {
+  /** Controlled visible month, if the consumer supplied one. */
+  focusDate?: ISODateString;
+  /** Selected value (single date or range), controlled or uncontrolled. */
+  value?: ISODateString | DateRange;
+  /** Earliest selectable date. */
+  min?: ISODateString;
+  /** Latest selectable date. */
+  max?: ISODateString;
+  /** How many month panes the calendar renders (1 or 2). */
+  numberOfMonths: number;
+  /** Today, injected so the caller keeps a single memoized source of "now". */
+  today: PlainDate;
+}
+
+/**
+ * Picks the date whose month the calendar opens on.
+ *
+ * An explicit `focusDate` wins, then the selected value — both are the
+ * consumer's own instruction about where to look, so neither is second-guessed
+ * against `min`/`max`.
+ *
+ * Otherwise the calendar opens on today, clamped into the `min`/`max` window.
+ * Without the clamp a window that doesn't contain today (a 2019 audit range, a
+ * booking window opening next spring) opened on today's month with every day
+ * disabled, leaving prev/next clicking as the only way in.
+ *
+ * When clamping forward to `min`, that month leads: the whole selectable window
+ * runs ahead of it. When clamping back to `max`, the last pane lands on `max`'s
+ * month instead — with `numberOfMonths={2}` opening on `[max, max + 1]` would
+ * spend half the calendar on a month that is entirely out of bounds. That
+ * shift never crosses `min`'s month.
+ */
+export function getInitialFocusDate(
+  options: InitialFocusDateOptions,
+): PlainDate {
+  const {focusDate, value, min, max, numberOfMonths, today} = options;
+
+  if (focusDate) {
+    return plainDateFromISO(focusDate);
+  }
+
+  if (value) {
+    return plainDateFromISO(typeof value === 'string' ? value : value.start);
+  }
+
+  const minDate = min ? plainDateFromISO(min) : null;
+  const maxDate = max ? plainDateFromISO(max) : null;
+
+  if (minDate && plainDateIsBefore(today, minDate)) {
+    return minDate;
+  }
+
+  if (maxDate && plainDateIsAfter(today, maxDate)) {
+    const lastPaneOffset = Math.max(0, numberOfMonths - 1);
+    const shifted = plainDateAddMonths(
+      plainDateSetFirstOfMonth(maxDate),
+      -lastPaneOffset,
+    );
+    if (
+      minDate &&
+      plainDateIsBefore(shifted, plainDateSetFirstOfMonth(minDate))
+    ) {
+      return minDate;
+    }
+    return shifted;
+  }
+
+  return today;
+}

package/src/Carousel/Carousel.tsx

@@ -46,11 +46,12 @@ import {useLayer} from '../Layer';
 import {useScrollOverflow} from '../hooks/useScrollOverflow';
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Imperative control surface for the Carousel, accessed via the `handleRef`
  * prop. Methods drive the same native-scroll machinery as the built-in
@@ -506,7 +507,7 @@ export function Carousel({
 
   return (
     <div
-      ref={mergeRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
+      ref={useMergedRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
       data-testid={testId}
       {...htmlProps}
       {...mergeProps(

package/src/Chat/ChatLayout.tsx

@@ -33,7 +33,7 @@ import {type ReactNode, useMemo, useRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useChatStreamScroll} from './useChatStreamScroll';
 import {useChatNewMessages} from './useChatNewMessages';
 import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
@@ -41,6 +41,7 @@ import {ChatLayoutContext} from './ChatContext';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -343,7 +344,7 @@ export function ChatLayout({
     <ChatLayoutContext value={layoutContext}>
       <div
         {...rest}
-        ref={mergeRefs(ref, rootRef)}
+        ref={useMergedRefs(ref, rootRef)}
         data-testid={testId}
         {...mergeProps(
           themeProps('chat-layout', {density}),