@astryxdesign/core 0.4.6 → 0.4.7-canary.0b6762d

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

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/Chat/ChatMessageList.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Message List',
   isHiddenFromOverview: true,
-  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
+  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,
   props: [
     {
       name: 'children',
@@ -45,6 +45,12 @@ export const docs = {
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
     },
+    {
+      name: 'align',
+      type: "'top' | 'bottom'",
+      description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",
+      default: "'bottom'",
+    },
     {
       name: 'isStreaming',
       type: 'boolean',
@@ -65,6 +71,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间，让简短对话贴近输入框；'top' 省略占位块，让消息从顶部开始。仅影响未填满的列表，溢出后两种模式滚动一致，保持自动滚动到底部。",
     isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
@@ -80,6 +87,7 @@ export const docsDense = {
     scrollToTopAction: 'async action at scroll top; load older msgs',
     density: 'visual density; flows to children via context',
     gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+    align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",
     isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {
     );
     expect(screen.getByTestId('chat-list')).toBeTruthy();
   });
+
+  // With no scrollToTopAction the spacer is the only aria-hidden element in
+  // the list, so its presence maps 1:1 to the aria-hidden count.
+  it('renders the bottom spacer by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('renders the bottom spacer when align="bottom"', () => {
+    render(
+      <ChatMessageList align="bottom" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('omits the spacer when align="top"', () => {
+    render(
+      <ChatMessageList align="top" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(0);
+  });
+
+  it('still renders children when align="top"', () => {
+    render(
+      <ChatMessageList align="top">
+        <ChatMessage sender="assistant">
+          <ChatMessageBubble>Hello</ChatMessageBubble>
+        </ChatMessage>
+      </ChatMessageList>,
+    );
+    expect(screen.getByText('Hello')).toBeTruthy();
+  });
 });

package/src/Chat/ChatMessageList.tsx

@@ -10,7 +10,8 @@
  *
  * Renders a container with role="log" for chat message histories.
  * Handles density context, configurable gap, empty state,
- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
+ * a configurable spacer (align) that pushes messages to the bottom,
+ * and an infinite scroll sentinel.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
  * ChatLayout. When used standalone (without a layout), the list
@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    */
   gap?: SpacingStep;
 
+  /**
+   * Vertical alignment of messages when the list is shorter than its
+   * container.
+   *
+   * - `'bottom'` (default): a spacer fills the free space and pushes
+   *   messages to the bottom, so a short conversation sits just above the
+   *   composer — the familiar messaging-app layout.
+   * - `'top'`: the spacer is omitted, so messages start at the top and grow
+   *   downward — better for document-style or log-style lists.
+   *
+   * This only changes the resting position of a non-full list. Once messages
+   * overflow the container the spacer collapses to zero in both modes, so
+   * ChatLayout auto-scroll-to-bottom behavior is identical either way.
+   *
+   * @default 'bottom'
+   */
+  align?: 'top' | 'bottom';
+
   /**
    * Whether an assistant message is actively streaming into the list.
    *
@@ -183,7 +202,8 @@ const gapStyles = stylex.create({
  *
  * Renders messages in a flex column with density-based spacing.
  * Override gap to tune row spacing separately from density.
- * A spacer pushes content to the bottom when the list isn't full.
+ * By default a spacer pushes content to the bottom when the list isn't full;
+ * set `align='top'` to start messages at the top instead.
  * Supports loading older messages via `scrollToTopAction`.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
@@ -204,6 +224,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  align = 'bottom',
   isStreaming = false,
   xstyle,
   className,
@@ -291,8 +312,11 @@ export function ChatMessageList({
             </div>
           )}
 
-          {/* Spacer pushes messages to bottom when list isn't full */}
-          <div {...stylex.props(styles.spacer)} aria-hidden />
+          {/* Spacer pushes messages to bottom when the list isn't full.
+              Omitted for top alignment so messages start at the top. */}
+          {align === 'bottom' && (
+            <div {...stylex.props(styles.spacer)} aria-hidden />
+          )}
 
           {/* Messages or empty state */}
           {hasChildren ? (

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -95,6 +95,12 @@ export const docs = {
       type: 'SyntaxThemeDefinition',
       description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
     },
+    {
+      name: 'highlightMode',
+      type: "'auto' | 'ranges' | 'spans'",
+      description: 'Syntax highlighting rendering mode.',
+      default: "'auto'",
+    },
     {
       name: 'isCollapsible',
       type: 'boolean',

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -58,6 +58,11 @@ export const docs = {
       description: 'Accessible name for the menu surface, announced when it opens.',
       default: "'Context menu'",
     },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description: 'Callback fired when the menu opens or closes.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',