@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Calendar/Calendar.test.tsx

@@ -12,8 +12,11 @@
 import {describe, it, expect, vi} from 'vitest';
 import {act, render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {getButton} from '../__tests__/fastRoleQueries';
+import * as stylex from '@stylexjs/stylex';
 import {Calendar} from './Calendar';
 import type {CalendarHandle} from './Calendar';
+import {calendarStyles} from './styles';
 
 /**
  * Helper to find a day button by its day number.
@@ -24,7 +27,7 @@ import type {CalendarHandle} from './Calendar';
 function getDayButton(day: number, month = 'January', year = 2026) {
   // Match the full date pattern with the day number
   const pattern = new RegExp(`${month}\\s+${day},\\s+${year}`);
-  return screen.getByRole('button', {name: pattern});
+  return getButton(pattern);
 }
 
 describe('Calendar', () => {
@@ -71,6 +74,24 @@ describe('Calendar', () => {
     expect(screen.getByText(expectedLabel)).toBeInTheDocument();
   });
 
+  it("marks today's cell with aria-current='date'", () => {
+    render(<Calendar />);
+
+    const now = new Date();
+    const iso = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+
+    const todayCell = document.querySelector(`button[data-date="${iso}"]`);
+    expect(todayCell).not.toBeNull();
+    expect(todayCell).toHaveAttribute('aria-current', 'date');
+
+    // Only today's cell is marked current.
+    const others = Array.from(
+      document.querySelectorAll('button[data-date]'),
+    ).filter(el => el.getAttribute('data-date') !== iso);
+    expect(others.length).toBeGreaterThan(0);
+    others.forEach(el => expect(el).not.toHaveAttribute('aria-current'));
+  });
+
   it('displays day names', () => {
     render(<Calendar />);
 
@@ -97,7 +118,11 @@ describe('Calendar', () => {
     render(<Calendar value="2026-01-15" focusDate="2026-01-01" />);
 
     const day15 = getDayButton(15);
-    expect(day15).toHaveAttribute('aria-selected', 'true');
+    // In an ARIA grid, selection state lives on the gridcell, not the button
+    // (a plain button role does not permit aria-selected).
+    const gridcell15 = day15.closest('[role="gridcell"]');
+    expect(gridcell15).toHaveAttribute('aria-selected', 'true');
+    expect(day15).not.toHaveAttribute('aria-selected');
   });
 
   it('calls onChange when date is selected', async () => {
@@ -123,7 +148,7 @@ describe('Calendar', () => {
     // Verify we start on February
     expect(screen.getByText('February 2026')).toBeInTheDocument();
 
-    const prevButton = screen.getByRole('button', {name: 'Previous month'});
+    const prevButton = getButton('Previous month');
     await user.click(prevButton);
 
     expect(screen.getByText('January 2026')).toBeInTheDocument();
@@ -137,7 +162,7 @@ describe('Calendar', () => {
     // Verify we start on January
     expect(screen.getByText('January 2026')).toBeInTheDocument();
 
-    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    const nextButton = getButton('Next month');
     await user.click(nextButton);
 
     expect(screen.getByText('February 2026')).toBeInTheDocument();
@@ -151,7 +176,7 @@ describe('Calendar', () => {
       <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
     );
 
-    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    const nextButton = getButton('Next month');
     await user.click(nextButton);
 
     expect(handleFocusChange).toHaveBeenCalledWith('2026-02-01');
@@ -209,12 +234,39 @@ describe('Calendar', () => {
 
     render(<Calendar numberOfMonths={2} focusDate="2026-01-01" />);
 
-    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    const nextButton = getButton('Next month');
     await user.click(nextButton);
 
     expect(screen.getByText(/February 2026.*March 2026/)).toBeInTheDocument();
   });
 
+  it('clamps out-of-range numberOfMonths to a single month', () => {
+    // 1000 would otherwise try to render 1000 month grids and lock the page up.
+    render(
+      <Calendar
+        numberOfMonths={1000 as unknown as 1 | 2}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // Only the focused month renders — no second month, no range separator.
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+    expect(screen.queryByText(/February 2026/)).not.toBeInTheDocument();
+  });
+
+  it('clamps numberOfMonths={0} to a single month', () => {
+    render(
+      <Calendar
+        numberOfMonths={0 as unknown as 1 | 2}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // 0 previously rendered no months at all; now falls back to one.
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+    expect(screen.getAllByRole('gridcell').length).toBeGreaterThan(0);
+  });
+
   // ─── Display Options ─────────────────────────────────────────
 
   it('shows week numbers when hasWeekNumbers is true', () => {
@@ -310,9 +362,22 @@ describe('Calendar', () => {
     const day12 = getDayButton(12);
     const day15 = getDayButton(15);
 
-    expect(day10).toHaveAttribute('aria-selected', 'true');
-    expect(day12).toHaveAttribute('aria-selected', 'true');
-    expect(day15).toHaveAttribute('aria-selected', 'true');
+    // Selection state lives on the gridcell wrapper, not the day button.
+    expect(day10.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day12.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day15.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day10).not.toHaveAttribute('aria-selected');
+    expect(day12).not.toHaveAttribute('aria-selected');
+    expect(day15).not.toHaveAttribute('aria-selected');
   });
 
   it('caps the range highlight next to a disabled mid-range day (#2715)', () => {
@@ -476,12 +541,8 @@ describe('Calendar', () => {
   it('has navigation buttons with accessible labels', () => {
     render(<Calendar />);
 
-    expect(
-      screen.getByRole('button', {name: 'Previous month'}),
-    ).toBeInTheDocument();
-    expect(
-      screen.getByRole('button', {name: 'Next month'}),
-    ).toBeInTheDocument();
+    expect(getButton('Previous month')).toBeInTheDocument();
+    expect(getButton('Next month')).toBeInTheDocument();
   });
 
   // ─── Bug Regression Tests ───────────────────────────────────
@@ -589,14 +650,14 @@ describe('Calendar', () => {
   it('prev button is disabled when focusDate month contains min', () => {
     render(<Calendar focusDate="2026-01-01" min="2026-01-15" />);
 
-    const prevButton = screen.getByRole('button', {name: 'Previous month'});
+    const prevButton = getButton('Previous month');
     expect(prevButton).toBeDisabled();
   });
 
   it('next button is disabled when focusDate month contains max', () => {
     render(<Calendar focusDate="2026-01-01" max="2026-01-15" />);
 
-    const nextButton = screen.getByRole('button', {name: 'Next month'});
+    const nextButton = getButton('Next month');
     expect(nextButton).toBeDisabled();
   });
 
@@ -675,4 +736,48 @@ describe('Calendar', () => {
       }
     }
   });
+
+  // ─── RTL (#3388) ─────────────────────────────────────────────
+
+  describe('RTL month navigation', () => {
+    // jsdom does not apply compiled StyleX CSS, so the scaleX(-1) mirror
+    // itself is only observable in a browser (see the dir="rtl" Storybook
+    // story). These tests pin the structure the fix depends on: both nav
+    // chevrons render inside the navIcon wrapper that carries the
+    // ':is([dir="rtl"] *)' conditional transform.
+    it('wraps both nav chevrons in the RTL-mirroring navIcon wrapper', () => {
+      render(<Calendar focusDate="2026-01-01" />);
+
+      const {className: navIconClass} = stylex.props(calendarStyles.navIcon);
+      expect(navIconClass).toBeTruthy();
+
+      for (const name of ['Previous month', 'Next month']) {
+        const button = getButton(name);
+        const wrappers = Array.from(button.querySelectorAll('span')).filter(
+          span => span.className === navIconClass,
+        );
+        expect(wrappers.length).toBe(1);
+      }
+    });
+
+    it('keeps navigation semantics unchanged under dir="rtl"', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <div dir="rtl">
+          <Calendar focusDate="2026-02-01" />
+        </div>,
+      );
+
+      expect(screen.getByText('February 2026')).toBeInTheDocument();
+
+      // DOM order and handlers must not change in RTL: flexbox already
+      // places "Previous month" at the visual right; only the glyph mirrors.
+      await user.click(getButton('Previous month'));
+      expect(screen.getByText('January 2026')).toBeInTheDocument();
+
+      await user.click(getButton('Next month'));
+      expect(screen.getByText('February 2026')).toBeInTheDocument();
+    });
+  });
 });

package/src/Calendar/Calendar.tsx

@@ -203,7 +203,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
     value,
     defaultValue,
     onChange,
-    numberOfMonths = 1,
+    numberOfMonths: numberOfMonthsProp = 1,
     min,
     max,
     dateConstraints,
@@ -223,6 +223,11 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // DayOfWeek so all downstream date math keeps working with an index.
   const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
 
+  // `numberOfMonths` is typed `1 | 2`; defensively clamp anything else that
+  // slips through at runtime to 1 so `Array.from({length})` can't render an
+  // absurd number of month grids (e.g. `numberOfMonths={1000}`).
+  const numberOfMonths = numberOfMonthsProp === 2 ? 2 : 1;
+
   // Today's date (memoized)
   const today = useMemo(() => plainDateToday(), []);
 
@@ -426,7 +431,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
         <Button
           label="Previous month"
           variant="ghost"
-          icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
+          icon={
+            // Wrapper span (not Icon props): Icon's string mode clobbers
+            // caller classNames, so the RTL mirror must live on its own
+            // element.
+            <span {...stylex.props(calendarStyles.navIcon)}>
+              <Icon icon="chevronLeft" size="sm" color="inherit" />
+            </span>
+          }
           onClick={() => navigateMonth(-1)}
           isDisabled={!canNavigatePrevious}
           isIconOnly
@@ -439,7 +451,11 @@ export function Calendar({ref, ...props}: CalendarProps) {
         <Button
           label="Next month"
           variant="ghost"
-          icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
+          icon={
+            <span {...stylex.props(calendarStyles.navIcon)}>
+              <Icon icon="chevronRight" size="sm" color="inherit" />
+            </span>
+          }
           onClick={() => navigateMonth(1)}
           isDisabled={!canNavigateNext}
           isIconOnly
@@ -912,7 +928,10 @@ function DayCell({
   });
 
   return (
-    <div role="gridcell" {...stylex.props(dayCellStyles.cell)}>
+    <div
+      role="gridcell"
+      aria-selected={state.isSelected || state.isInRange || undefined}
+      {...stylex.props(dayCellStyles.cell)}>
       {/* Range background */}
       {state.isInRange && (
         <div
@@ -952,8 +971,10 @@ function DayCell({
         type="button"
         data-date={day.iso}
         aria-label={plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY)}
-        aria-selected={state.isSelected || state.isInRange || undefined}
         aria-disabled={state.effectivelyDisabled || undefined}
+        // Mark today's cell programmatically (APG date-picker pattern), not just
+        // visually, so screen-reader users can identify the current date.
+        aria-current={state.isToday ? 'date' : undefined}
         disabled={isDisabled}
         // Initial roving tab-stop seed; useGridFocus owns it after mount.
         tabIndex={isTabbableDay ? 0 : -1}

package/src/Calendar/dayCellUtils.ts

@@ -193,7 +193,9 @@ export function isRangeHighlighted(input: {
   isDisabled: boolean;
   isOutside: boolean;
 }): boolean {
-  if (input.mode !== 'range') {return false;}
+  if (input.mode !== 'range') {
+    return false;
+  }
   return isSpanHighlighted({
     date: input.date,
     spanStart: input.rangeStart,

package/src/Calendar/styles.ts

@@ -64,9 +64,19 @@ export const calendarStyles = stylex.create({
     whiteSpace: 'nowrap',
     borderWidth: 0,
   },
+  /**
+   * Wrapper for the month nav chevrons. In RTL the flex header already
+   * swaps the buttons' visual sides; the glyphs must mirror with them so
+   * "Previous month" points outward (visually right) instead of inward.
+   * Keyed on the dir attribute (dir="rtl"), same as MobileNav's drawer
+   * transform — bare CSS `direction: rtl` alone won't trigger it.
+   */
   navIcon: {
-    width: spacingVars['--spacing-4'],
-    height: spacingVars['--spacing-4'],
+    display: 'inline-flex',
+    transform: {
+      default: null,
+      ':is([dir="rtl"] *)': 'scaleX(-1)',
+    },
   },
 });
 

package/src/Card/Card.doc.mjs

@@ -131,7 +131,7 @@ export const docsZh = {
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card'},
+      {className: 'astryx-card', visualProps: ['variant']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},

package/src/Card/Card.tsx

@@ -44,8 +44,10 @@ import {themeProps} from '../utils/themeProps';
  * - Non-semantic palette: `blue | cyan | gray | green | orange | pink | purple | red | teal | yellow`
  *   Each uses the corresponding `--color-background-<name>` token (20% opacity tint).
  *
- * All variants include a transparent border to prevent layout jitter
- * when switching variants. Themes can override borderWidth/borderColor.
+ * Only `default` draws a visible border. Its border width is subtracted from
+ * the padding so the total inset (border + padding) equals the padding token —
+ * keeping content geometry faithful to the spacing scale and identical to the
+ * borderless variants. Themes can override borderWidth/borderColor.
  */
 export type CardVariant =
   | 'default'
@@ -71,12 +73,18 @@ const styles = stylex.create({
     '--_card-radius': radiusVars['--radius-container'],
     borderRadius: 'var(--_card-radius)',
     overflow: 'clip',
-    borderWidth: borderVars['--border-width'],
-    borderStyle: 'solid',
-    borderColor: 'transparent',
   },
+  // The border is drawn *inside* the padding — its width is subtracted from
+  // each side — so total inset (border + padding) equals the padding token
+  // rather than exceeding it by the border width.
   withBorder: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
     borderColor: colorVars['--color-border-emphasized'],
+    paddingInlineStart: `calc(var(--container-padding-inline-start) - ${borderVars['--border-width']})`,
+    paddingInlineEnd: `calc(var(--container-padding-inline-end) - ${borderVars['--border-width']})`,
+    paddingBlockStart: `calc(var(--container-padding-block-start) - ${borderVars['--border-width']})`,
+    paddingBlockEnd: `calc(var(--container-padding-block-end) - ${borderVars['--border-width']})`,
   },
   // Fixed-height cards scroll content; overflow: auto also clips to border-radius
   scrollable: {
@@ -266,7 +274,6 @@ export function Card({
         stylex.props(
           styles.card,
           variantStyles[variant],
-          variant === 'default' && styles.withBorder,
           hasFixedHeight && styles.scrollable,
           dynamicStyles.sizing(
             width ?? null,
@@ -296,6 +303,9 @@ export function Card({
           !useThemeDefault &&
             effectivePadding !== 4 &&
             containerPaddingBlockEndVarStyles[effectivePadding],
+          // Applied after the container padding so the border-inset calc wins;
+          // it reads the --container-padding-* vars set above.
+          variant === 'default' && styles.withBorder,
           xstyle,
         ),
         className,

package/src/Carousel/Carousel.doc.mjs

@@ -20,15 +20,15 @@ export const docs = {
     ],
     anatomy: [
       {name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
-      {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
+      {name: 'Items', required: true, description: 'The children rendered in a row inside the scroll container. With hasSnap, each item snaps to the start edge.'},
       {name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
-      {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
+      {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear when the content can scroll in that direction. Enabled by default, disable with hasButtons={false}.'},
     ],
   },
   props: [
     {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
     {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
-    {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+    {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons when content is scrollable.', default: 'true'},
     {name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
     {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
@@ -59,20 +59,20 @@ export const docs = {
 export const docsZh = {
   usage: {
     description:
-      'Carousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.',
+      'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表，或任何希望无需占据整页即可浏览的项目集合。',
     bestPractices: [
-      {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
-      {guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
-      {guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
-      {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
-      {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
-      {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
+      {guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附，例如画廊或产品列表。'},
+      {guidance: true, description: '始终提供描述轮播内容的 aria-label，例如"精选产品"或"团队成员"。'},
+      {guidance: true, description: '使用一致的间距和项目宽度，让轮播看起来是有意为之，而不是内容意外溢出。'},
+      {guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动，关键内容应放在首屏。'},
+      {guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
+      {guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
     ],
   },
   propDescriptions: {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
-    hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasButtons: '内容可滚动时显示上一个/下一个导航按钮。',
     hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
     padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
@@ -98,7 +98,7 @@ export const docsDense = {
   propDescriptions: {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
-    hasButtons: 'prev/next buttons on hover (desktop)',
+    hasButtons: 'prev/next buttons when content is scrollable',
     hasEdgeFade: 'gradient edge-fade mask on overflow',
     hasSnap: 'scroll-snap; children snap to start edge',
     padding: 'inline padding; scroll-padding keeps snap points on content edge',

package/src/Carousel/Carousel.test.tsx

@@ -38,6 +38,19 @@ describe('Carousel', () => {
     expect(region).toHaveAttribute('aria-roledescription', 'carousel');
   });
 
+  it('makes the scroll container keyboard-focusable', () => {
+    render(
+      <Carousel aria-label="Photos">
+        <div>Item</div>
+      </Carousel>,
+    );
+    // The inner scroll container overflows, so it must be reachable by
+    // keyboard (axe: scrollable-region-focusable).
+    const region = screen.getByRole('region', {name: 'Photos'});
+    const scroller = region.firstElementChild;
+    expect(scroller).toHaveAttribute('tabindex', '0');
+  });
+
   it('applies data-testid', () => {
     render(
       <Carousel data-testid="my-carousel">

package/src/Carousel/Carousel.tsx

@@ -318,6 +318,8 @@ export function Carousel({
           : null
     : null;
 
+  // Self-authored position styles (positioning: 'custom' below): a cover
+  // centered on the anchor, sized to it — direction-neutral by construction.
   const coverStyle: React.CSSProperties = {
     positionArea: 'center',
     width: 'anchor-size(width)',
@@ -340,6 +342,7 @@ export function Carousel({
       {...htmlProps}>
       <div
         ref={composedRef}
+        tabIndex={0}
         {...stylex.props(
           styles.scroller,
           gapStyles[gap],
@@ -397,8 +400,7 @@ export function Carousel({
             </div>
           </>,
           {
-            placement: 'below',
-            alignment: 'center',
+            positioning: 'custom',
             style: coverStyle,
             xstyle: styles.buttonOverlay,
           },

package/src/Chat/Chat.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
       {className: 'astryx-chat-composer', visualProps: ['density']},
       {className: 'astryx-chat-composer-input'},
       {className: 'astryx-chat-composer-drawer', visualProps: ['collapsed']},
-      {className: 'astryx-chat-message', visualProps: ['sender']},
+      {className: 'astryx-chat-message', visualProps: ['sender', 'density']},
       {
         className: 'astryx-chat-message-bubble',
         visualProps: ['sender', 'variant', 'density'],

package/src/Chat/ChatComposerInput.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import {ChatComposer} from './ChatComposer';
 import {ChatComposerInput} from './ChatComposerInput';
 import type {
   ChatComposerTrigger,
@@ -129,6 +130,29 @@ describe('ChatComposerInput', () => {
       fireEvent.keyDown(textbox, {key: 'Enter'});
       expect(onSubmit).not.toHaveBeenCalled();
     });
+
+    it('keeps parent submit flow when child onChange observes input changes', () => {
+      const onSubmit = vi.fn();
+      const onInputChange = vi.fn();
+      render(
+        <ChatComposer
+          onSubmit={onSubmit}
+          input={<ChatComposerInput onChange={onInputChange} />}
+        />,
+      );
+
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello world';
+      fireEvent.input(textbox);
+
+      expect(onInputChange).toHaveBeenLastCalledWith('hello world');
+
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+
+      expect(onSubmit).toHaveBeenCalledWith('hello world');
+      expect(onInputChange).toHaveBeenLastCalledWith('');
+      expect(textbox.textContent).toBe('');
+    });
   });
 
   // Controlled-value sync used to overwrite `textContent` on every
@@ -345,7 +369,9 @@ describe('ChatComposerInput', () => {
         },
       });
 
-      expect(textbox.querySelector('[data-astryx-token]')).not.toBeInTheDocument();
+      expect(
+        textbox.querySelector('[data-astryx-token]'),
+      ).not.toBeInTheDocument();
       expect(textbox.textContent).toBe(long);
     });
   });

package/src/Chat/ChatComposerInput.tsx

@@ -43,10 +43,7 @@ import {
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {useTriggerMenu} from './useTriggerMenu';
-import {
-  useChatComposerTokens,
-  isCustomToken,
-} from './useChatComposerTokens';
+import {useChatComposerTokens, isCustomToken} from './useChatComposerTokens';
 import {ensureCaretInside, insertTextAtCursor} from './chatComposerSelection';
 import {ChatPastedTextToken} from './ChatPastedTextToken';
 import {
@@ -283,12 +280,13 @@ function serialize(node: Node): string {
 
 export function ChatComposerInput(props: ChatComposerInputProps) {
   const composerCtx = useChatComposerContext();
+  const hasControlledValueProp = props.value !== undefined;
 
   const {
     ref,
     handleRef,
     value: controlledValue = composerCtx?.value,
-    onChange = composerCtx?.onChange,
+    onChange: onChangeProp,
     placeholder = composerCtx?.placeholder ?? 'Type a message\u2026',
     maxRows = 8,
     triggers,
@@ -306,6 +304,21 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     ...rest
   } = props;
 
+  const composerOnChange = composerCtx?.onChange;
+  const onChange = useCallback(
+    (nextValue: string) => {
+      if (hasControlledValueProp) {
+        onChangeProp?.(nextValue);
+        return;
+      }
+      composerOnChange?.(nextValue);
+      if (onChangeProp !== composerOnChange) {
+        onChangeProp?.(nextValue);
+      }
+    },
+    [composerOnChange, hasControlledValueProp, onChangeProp],
+  );
+
   const editableRef = useRef<HTMLDivElement>(null);
   const selfRef = useRef<ChatComposerInputHandle>(null);
   const [isEmpty, setIsEmpty] = useState(true);
@@ -679,11 +692,7 @@ ChatComposerInput.displayName = 'ChatComposerInput';
 // Token element helper (for custom rendering in stories/consumers)
 // =============================================================================
 
-export function ChatComposerTokenElement({
-  token,
-}: {
-  token: ChatComposerToken;
-}) {
+export function ChatComposerTokenElement({token}: {token: ChatComposerToken}) {
   return (
     <span
       data-astryx-token=""
@@ -693,11 +702,7 @@ export function ChatComposerTokenElement({
       {isCustomToken(token) ? (
         token.render()
       ) : (
-        <Badge
-          label={token.label}
-          variant={token.variant}
-          icon={token.icon}
-        />
+        <Badge label={token.label} variant={token.variant} icon={token.icon} />
       )}
     </span>
   );