@astryxdesign/core 0.1.2 → 0.1.3-canary.1e94ba0

package/src/Calendar/Calendar.tsx

@@ -32,7 +32,6 @@ import {useGridFocus} from '../hooks';
 import {
   useCalendarDays,
   useCalendarConstraints,
-  useCalendarRovingTabindex,
   type CalendarDay,
 } from './hooks';
 import {
@@ -46,7 +45,6 @@ import {
   plainDateFromISO,
   plainDateToISO,
   plainDateToDate,
-  plainDateFromDate,
   plainDateToday,
   plainDateSetFirstOfMonth,
   plainDateAddMonths,
@@ -70,8 +68,19 @@ import {
 // Types
 // =============================================================================
 
-export type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';
-import type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';
+export type {
+  ISODateString,
+  DayOfWeek,
+  DayOfWeekName,
+  DateRange,
+} from '../utils/dateTypes';
+import type {
+  ISODateString,
+  DayOfWeek,
+  DayOfWeekName,
+  DateRange,
+} from '../utils/dateTypes';
+import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
 
 /** Imperative handle for Calendar handleRef */
@@ -134,10 +143,11 @@ interface CalendarBaseProps extends Omit<
   hasVariableRowCount?: boolean;
 
   /**
-   * First day of week.
+   * First day of week. Accepts a number (0 = Sunday … 6 = Saturday) or a
+   * three-letter day name ('sun'–'sat', case-insensitive) for readability.
    * Default: 0 (Sunday)
    */
-  weekStartsOn?: DayOfWeek;
+  weekStartsOn?: DayOfWeek | DayOfWeekName;
 }
 
 // ─── Mode-specific Props (discriminated union) ────────────────
@@ -200,13 +210,17 @@ export function Calendar({ref, ...props}: CalendarProps) {
     hasOutsideDays = true,
     hasWeekNumbers = false,
     hasVariableRowCount = false,
-    weekStartsOn = 0,
+    weekStartsOn: weekStartsOnProp = 0,
     xstyle,
     className,
     style,
     ...rest
   } = props;
 
+  // Normalize `weekStartsOn` (number or three-letter day name) to a numeric
+  // DayOfWeek so all downstream date math keeps working with an index.
+  const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
+
   // Today's date (memoized)
   const today = useMemo(() => plainDateToday(), []);
 
@@ -539,33 +553,52 @@ function MonthGrid({
     return null;
   }, [mode, value]);
 
-  const {isTabbable} = useCalendarRovingTabindex({
-    days,
-    today,
-    year,
-    month: month.month,
-    isDateDisabled,
-    selectedDate: selectedDateForTabindex,
-  });
+  // Seed the initial roving tab stop for this month. useGridFocus owns the
+  // live tab stop (see `hasRovingTabIndex` below) — it honors an existing
+  // `tabindex="0"` and repairs/moves it thereafter — so this only decides
+  // which day button starts tabbable. Priority: selected date (if visible and
+  // enabled) > today (if visible and enabled) > first enabled in-month day.
+  const seedTabbableIso = useMemo((): ISODateString | null => {
+    if (selectedDateForTabindex) {
+      const isSelectedInMonth =
+        selectedDateForTabindex.year === year &&
+        selectedDateForTabindex.month === month.month;
+      if (isSelectedInMonth && !isDateDisabled(selectedDateForTabindex)) {
+        return plainDateToISO(selectedDateForTabindex);
+      }
+    }
+
+    const isTodayInMonth = today.year === year && today.month === month.month;
+    if (isTodayInMonth && !isDateDisabled(today)) {
+      return plainDateToISO(today);
+    }
 
-  // Helper to get the focused date from the currently focused element
+    for (const day of days) {
+      if (!day.isOutside && !isDateDisabled(day.date)) {
+        return day.iso;
+      }
+    }
+
+    return null;
+  }, [days, today, year, month.month, isDateDisabled, selectedDateForTabindex]);
+
+  // Helper to get the focused date from the currently focused element.
+  // Reads the machine-readable `data-date` (ISO) attribute rather than parsing
+  // the human-readable `aria-label` with `new Date()`, which is locale/format
+  // dependent and returns Invalid Date in non-English locales (e.g. fr-FR,
+  // ja-JP), silently swallowing month-boundary arrow navigation (complex-4).
   const getFocusedDate = useCallback((): ISODateString | null => {
     const activeElement = document.activeElement as HTMLElement | null;
     if (!activeElement) {
       return null;
     }
 
-    const ariaLabel = activeElement.getAttribute('aria-label');
-    if (!ariaLabel) {
+    const iso = activeElement.getAttribute('data-date');
+    if (!iso) {
       return null;
     }
 
-    const parsed = new Date(ariaLabel);
-    if (isNaN(parsed.getTime())) {
-      return null;
-    }
-
-    return plainDateToISO(plainDateFromDate(parsed));
+    return iso as ISODateString;
   }, []);
 
   // Handle navigation to previous month
@@ -605,16 +638,31 @@ function MonthGrid({
     }
   }, [getFocusedDate, onNavigateNext]);
 
-  // Grid focus navigation
-  const {gridRef, handleKeyDown: handleGridKeyDown} =
-    useGridFocus<HTMLDivElement>({
-      columns: 7,
-      cellSelector: 'button:not([disabled])',
-      onNavigateBefore: handleNavigatePrevious,
-      onNavigateAfter: handleNavigateNext,
-      onPageUp: handlePageUp,
-      onPageDown: handlePageDown,
-    });
+  // Grid focus navigation.
+  //
+  // The hook enumerates ALL grid cells (every `role="gridcell"`, including
+  // disabled days and empty placeholder cells) so the true 7-column geometry is
+  // preserved. `isCellFocusable` / `getFocusTarget` tell the hook which cells
+  // can take focus (those containing an enabled day button) and where to send
+  // focus (the day button inside the cell). Arrow keys move to the target
+  // row/column and, if that cell is disabled, continue in the same direction to
+  // the next enabled cell.
+  const {
+    gridRef,
+    handleKeyDown: handleGridKeyDown,
+    handleFocus: handleGridFocus,
+  } = useGridFocus<HTMLDivElement>({
+    columns: 7,
+    cellSelector: '[role="gridcell"]',
+    isCellFocusable: cell =>
+      cell.querySelector('button:not([disabled])') !== null,
+    getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
+    hasRovingTabIndex: true,
+    onNavigateBefore: handleNavigatePrevious,
+    onNavigateAfter: handleNavigateNext,
+    onPageUp: handlePageUp,
+    onPageDown: handlePageDown,
+  });
 
   // Handle pending focus after month navigation
   useEffect(() => {
@@ -627,11 +675,11 @@ function MonthGrid({
     );
 
     const targetPd = plainDateFromISO(pendingFocus);
-    const targetLabel = plainDateFormat(targetPd, DATE_FORMAT_WITH_WEEKDAY);
+    const targetIso = plainDateToISO(targetPd);
 
     let targetButton: HTMLElement | null = null;
     for (const button of buttons) {
-      if (button.getAttribute('aria-label') === targetLabel) {
+      if (button.getAttribute('data-date') === targetIso) {
         targetButton = button;
         break;
       }
@@ -688,40 +736,38 @@ function MonthGrid({
 
   return (
     <div {...stylex.props(monthGridStyles.monthGrid)}>
-      {/* Day names header */}
-      <div
-        {...stylex.props(
-          monthGridStyles.weekHeader,
-          hasWeekNumbers && monthGridStyles.weekHeaderWithNumbers,
-        )}>
-        {hasWeekNumbers && (
-          <div
-            {...stylex.props(
-              monthGridStyles.dayName,
-              monthGridStyles.weekNumberHeader,
-            )}
-          />
-        )}
-        {dayNames.map(name => (
-          <div
-            key={name}
-            role="columnheader"
-            {...stylex.props(monthGridStyles.dayName)}>
-            {name}
-          </div>
-        ))}
-      </div>
-
-      {/* Days grid */}
+      {/* Days grid (APG grid: header row of columnheaders + week rows) */}
       <div
         ref={gridRef}
         role="grid"
         aria-label={monthLabel}
         onKeyDown={handleGridKeyDown}
+        onFocus={handleGridFocus}
         {...stylex.props(
           monthGridStyles.daysGrid,
           hasWeekNumbers && monthGridStyles.daysGridWithNumbers,
         )}>
+        {/* Day names header row (columnheaders live inside the grid). Uses the
+            same display:contents row so its cells align to the grid columns. */}
+        <div role="row" {...stylex.props(monthGridStyles.weekRow)}>
+          {hasWeekNumbers && (
+            <div
+              {...stylex.props(
+                monthGridStyles.dayName,
+                monthGridStyles.weekNumberHeader,
+              )}
+            />
+          )}
+          {dayNames.map(name => (
+            <div
+              key={name}
+              role="columnheader"
+              {...stylex.props(monthGridStyles.dayName)}>
+              {name}
+            </div>
+          ))}
+        </div>
+
         {weeks.map(week => {
           const weekDate = week.find(d => !d.isOutside)?.date || week[0].date;
           const weekNum = plainDateGetWeekNumber(weekDate);
@@ -732,7 +778,9 @@ function MonthGrid({
               role="row"
               {...stylex.props(monthGridStyles.weekRow)}>
               {hasWeekNumbers && (
-                <div {...stylex.props(monthGridStyles.weekNumber)}>
+                <div
+                  role="rowheader"
+                  {...stylex.props(monthGridStyles.weekNumber)}>
                   {weekNum}
                 </div>
               )}
@@ -750,7 +798,7 @@ function MonthGrid({
                   today={today}
                   hasOutsideDays={hasOutsideDays}
                   isDisabled={isDateDisabled(day.date)}
-                  isTabbable={isTabbable(day.iso)}
+                  isTabbable={day.iso === seedTabbableIso}
                   onDayClick={onDayClick}
                   onDayHover={onDayHover}
                 />
@@ -779,6 +827,11 @@ interface DayCellProps {
   today: PlainDate;
   hasOutsideDays: boolean;
   isDisabled: boolean;
+  /**
+   * Whether this day seeds the initial roving tab stop. useGridFocus
+   * (`hasRovingTabIndex`) owns the live tab stop thereafter — it honors an
+   * existing `tabindex="0"` and repairs/moves it on navigation and focus.
+   */
   isTabbable: boolean;
   onDayClick: (date: PlainDate) => void;
   onDayHover: (date: PlainDate | null) => void;
@@ -803,7 +856,9 @@ function DayCell({
   const {date, isOutside, dayNumber} = day;
 
   if (isOutside && !hasOutsideDays) {
-    return <div {...stylex.props(dayCellStyles.cell)} />;
+    // Empty placeholder cell — still a gridcell so the grid geometry stays a
+    // clean 7-per-row set for keyboard navigation.
+    return <div role="gridcell" {...stylex.props(dayCellStyles.cell)} />;
   }
 
   const state = computeDayCellState({
@@ -825,7 +880,7 @@ function DayCell({
   const previewRounding = computePreviewRounding(state);
 
   return (
-    <div {...stylex.props(dayCellStyles.cell)}>
+    <div role="gridcell" {...stylex.props(dayCellStyles.cell)}>
       {/* Range background */}
       {state.isInRange && (
         <div
@@ -863,12 +918,12 @@ function DayCell({
       {/* Day button */}
       <button
         type="button"
-        role="gridcell"
         data-date={day.iso}
         aria-label={plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY)}
         aria-selected={state.isSelected || state.isInRange || undefined}
         aria-disabled={state.effectivelyDisabled || undefined}
         disabled={isDisabled}
+        // Initial roving tab-stop seed; useGridFocus owns it after mount.
         tabIndex={isTabbableDay ? 0 : -1}
         onClick={() => !state.effectivelyDisabled && onDayClick(date)}
         onMouseEnter={() => !state.effectivelyDisabled && onDayHover(date)}

package/src/Calendar/hooks/index.ts

@@ -27,9 +27,3 @@ export type {
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
 } from './useCalendarNavigation';
-
-export {useCalendarRovingTabindex} from './useCalendarRovingTabindex';
-export type {
-  UseCalendarRovingTabindexOptions,
-  UseCalendarRovingTabindexReturn,
-} from './useCalendarRovingTabindex';

package/src/Calendar/index.ts

@@ -17,6 +17,7 @@ export type {
   CalendarHandle,
   ISODateString,
   DayOfWeek,
+  DayOfWeekName,
   DateRange,
 } from './Calendar';
 
@@ -25,7 +26,6 @@ export {
   useCalendarDays,
   useCalendarConstraints,
   useCalendarNavigation,
-  useCalendarRovingTabindex,
 } from './hooks';
 export type {
   CalendarDay,
@@ -35,8 +35,6 @@ export type {
   UseCalendarConstraintsReturn,
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
-  UseCalendarRovingTabindexOptions,
-  UseCalendarRovingTabindexReturn,
 } from './hooks';
 
 // Re-export calendar-specific utilities for advanced usage

package/src/Calendar/styles.ts

@@ -78,17 +78,12 @@ export const monthGridStyles = stylex.create({
   monthGrid: {
     flex: '1 1 0',
   },
-  weekHeader: {
-    display: 'grid',
-    gridTemplateColumns: 'repeat(7, 1fr)',
-    marginBottom: spacingVars['--spacing-1'],
-  },
-  weekHeaderWithNumbers: {
-    gridTemplateColumns: 'auto repeat(7, 1fr)',
-  },
   dayName: {
     width: sizeVars['--size-element-md'],
-    height: sizeVars['--size-element-md'],
+    // Restores the small gap the standalone header used to have below it.
+    height: `calc(${sizeVars['--size-element-md']} + ${spacingVars['--spacing-1']})`,
+    paddingBottom: spacingVars['--spacing-1'],
+    boxSizing: 'border-box',
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',

package/src/Carousel/Carousel.doc.mjs

@@ -21,7 +21,7 @@ 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: 'Fade edges', required: true, description: 'Gradient fades on the left and right edges that indicate more content is available.'},
+      {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}.'},
     ],
   },
@@ -29,7 +29,9 @@ export const docs = {
     {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: '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.'},
     {name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
     {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
@@ -71,7 +73,9 @@ export const docsZh = {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
     hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
+    padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
     'aria-label': '轮播区域的无障碍标签。',
   },
 };
@@ -95,7 +99,9 @@ export const docsDense = {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
     hasButtons: 'prev/next buttons on hover (desktop)',
+    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',
     'aria-label': 'accessible label for carousel region',
     'data-testid': 'test selector for automated testing frameworks',
   },

package/src/Carousel/Carousel.test.tsx

@@ -78,4 +78,24 @@ describe('Carousel', () => {
     expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
     expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
   });
+
+  it('disables edge scroll buttons instead of removing them from the tab order', () => {
+    // In jsdom there is no measurable overflow, so both edges are at rest and
+    // the scroll buttons are in their hidden/inert state. They must stay
+    // mounted but be disabled — a disabled <button> is skipped by the tab
+    // order and hidden from the a11y tree, so keyboard users don't focus an
+    // invisible control (WCAG 2.4.7).
+    render(
+      <Carousel aria-label="Edge state">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Carousel>,
+    );
+    const left = screen.getByLabelText('Scroll left');
+    const right = screen.getByLabelText('Scroll right');
+    expect(left).toBeInTheDocument();
+    expect(right).toBeInTheDocument();
+    expect(left).toBeDisabled();
+    expect(right).toBeDisabled();
+  });
 });

package/src/Carousel/Carousel.tsx

@@ -295,9 +295,16 @@ export function Carousel({
     const firstChild = el.firstElementChild as HTMLElement | null;
     const itemWidth = firstChild ? firstChild.offsetWidth : 0;
     const amount = el.clientWidth - itemWidth * 0.5;
+    // Respect the user's reduced-motion preference — mirrors the CSS
+    // scroll-behavior override so button-driven scrolling doesn't animate
+    // for users who opted out of motion.
+    const prefersReducedMotion =
+      typeof window !== 'undefined' &&
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
     el.scrollBy({
       left: direction * Math.max(amount, itemWidth),
-      behavior: 'smooth',
+      behavior: prefersReducedMotion ? 'auto' : 'smooth',
     });
   }, []);
 
@@ -360,6 +367,11 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // Disabled when there's nothing to scroll toward. Keeps the
+                // button mounted (stable layout/focus) but removes it from the
+                // tab order and a11y tree while it's visually hidden, so
+                // keyboard users don't land on an invisible control.
+                isDisabled={!overflowStart}
                 onClick={() => scrollBy(-1)}
                 xstyle={styles.buttonRadiusOverride}
               />
@@ -376,6 +388,9 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // See "Scroll left" — disabled while visually hidden so the
+                // button stays mounted but out of the tab order / a11y tree.
+                isDisabled={!overflowEnd}
                 onClick={() => scrollBy(1)}
                 xstyle={styles.buttonRadiusOverride}
               />

package/src/Center/Center.doc.mjs

@@ -18,14 +18,24 @@ export const docs = {
     },
     {
       name: 'width',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container width (px or CSS value).',
     },
     {
       name: 'height',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container height (px or CSS value).',
     },
+    {
+      name: 'maxWidth',
+      type: 'SizeValue',
+      description: 'Maximum container width (px or CSS value).',
+    },
+    {
+      name: 'minHeight',
+      type: 'SizeValue',
+      description: 'Minimum container height (px or CSS value).',
+    },
     {
       name: 'isInline',
       type: 'boolean',

package/src/Center/Center.tsx

@@ -39,15 +39,21 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (width: SizeValue | null, height: SizeValue | null) => ({
+  sizing: (
+    width: SizeValue | null,
+    height: SizeValue | null,
+    maxWidth: SizeValue | null,
+    minHeight: SizeValue | null,
+  ) => ({
     width,
     height,
+    maxWidth,
+    minHeight,
   }),
 });
 
 export type CenterAxis = 'both' | 'horizontal' | 'vertical';
 
-
 export interface CenterProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -72,6 +78,18 @@ export interface CenterProps extends BaseProps<HTMLDivElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Whether to make the container inline-flex (useful for text/icons).
    * @default false
@@ -101,6 +119,8 @@ export function Center({
   axis = 'both',
   width,
   height,
+  maxWidth,
+  minHeight,
   isInline = false,
   children,
   xstyle,
@@ -115,7 +135,12 @@ export function Center({
       isInline ? styles.inline : styles.base,
       (axis === 'both' || axis === 'vertical') && styles.alignItemsCenter,
       (axis === 'both' || axis === 'horizontal') && styles.justifyContentCenter,
-      dynamicStyles.sizing(width ?? null, height ?? null),
+      dynamicStyles.sizing(
+        width ?? null,
+        height ?? null,
+        maxWidth ?? null,
+        minHeight ?? null,
+      ),
       xstyle,
     ),
     className,

package/src/Chat/ChatComposerInput.test.tsx

@@ -409,18 +409,36 @@ describe('ChatComposerInput', () => {
   });
 
   describe('accessibility', () => {
-    it('has aria-haspopup on the textbox', () => {
+    it('exposes role=combobox when triggers are configured', () => {
       const triggers = [createMentionTrigger()];
       render(<ChatComposerInput triggers={triggers} />);
-      const textbox = screen.getByRole('textbox');
-      expect(textbox).toHaveAttribute('aria-haspopup', 'listbox');
+      // aria-expanded/haspopup/controls/activedescendant are only valid on
+      // role="combobox", so the editable element must be a combobox (not a
+      // plain textbox) whenever trigger-menu behavior is wired.
+      expect(screen.getByRole('combobox')).toBeInTheDocument();
+      expect(screen.queryByRole('textbox')).not.toBeInTheDocument();
+    });
+
+    it('has aria-haspopup on the combobox', () => {
+      const triggers = [createMentionTrigger()];
+      render(<ChatComposerInput triggers={triggers} />);
+      const combobox = screen.getByRole('combobox');
+      expect(combobox).toHaveAttribute('aria-haspopup', 'listbox');
     });
 
     it('has aria-expanded=false when menu is closed', () => {
       const triggers = [createMentionTrigger()];
       render(<ChatComposerInput triggers={triggers} />);
-      const textbox = screen.getByRole('textbox');
-      expect(textbox).toHaveAttribute('aria-expanded', 'false');
+      const combobox = screen.getByRole('combobox');
+      expect(combobox).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('stays role=textbox with no combobox attributes when no triggers are configured', () => {
+      render(<ChatComposerInput label="Message" />);
+      const textbox = screen.getByRole('textbox', {name: 'Message'});
+      // A plain textbox must not carry combobox-only ARIA (axe: aria-allowed-attr).
+      expect(textbox).not.toHaveAttribute('aria-expanded');
+      expect(textbox).not.toHaveAttribute('aria-haspopup');
     });
   });
 
@@ -590,7 +608,8 @@ describe('ChatComposerInput', () => {
       const result = render(
         <ChatComposerInput triggers={triggers} onChange={onChange} />,
       );
-      const textbox = screen.getByRole('textbox');
+      // With triggers configured the editable is a combobox, not a textbox.
+      const textbox = screen.getByRole('combobox');
       textbox.focus();
       return {...result, textbox, onChange};
     }
@@ -684,7 +703,7 @@ describe('ChatComposerInput', () => {
           onChange={onChange}
         />,
       );
-      const textbox = screen.getByRole('textbox');
+      const textbox = screen.getByRole('combobox');
       textbox.focus();
 
       setCursorAfterText(textbox, 'hello @');

package/src/Chat/ChatComposerInput.tsx

@@ -632,7 +632,6 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
       )}
       <div
         ref={editableRef}
-        role="textbox"
         aria-multiline="true"
         aria-label={label}
         contentEditable={!isDisabled}

package/src/Chat/ChatDictationButton.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
       name: 'dictation',
       type: 'UseSpeechRecognitionReturn',
       description:
-        'The return value from useChatDictation or useSpeechRecognition. Controls all button state \u2014 listening, volume, bands, and toggle.',
+        'The return value from useChatDictation or useSpeechRecognition. Controls all button state: listening, volume, bands, and toggle.',
       required: true,
     },
     {