@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Carousel/Carousel.test.tsx

@@ -92,6 +92,59 @@ describe('Carousel', () => {
     expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
   });
 
+  describe('slide semantics', () => {
+    it('exposes each slide as a group with aria-roledescription="slide" and a positional name', () => {
+      render(
+        <Carousel aria-label="Photos">
+          <div>One</div>
+          <div>Two</div>
+          <div>Three</div>
+        </Carousel>,
+      );
+      // APG carousel pattern: each slide container is role=group with
+      // aria-roledescription="slide" and an "N of M" accessible name.
+      const slides = screen.getAllByRole('group');
+      expect(slides).toHaveLength(3);
+      slides.forEach((slide, i) => {
+        expect(slide).toHaveAttribute('aria-roledescription', 'slide');
+        expect(slide).toHaveAccessibleName(`Slide ${i + 1} of 3`);
+      });
+    });
+
+    it('reflects the rendered child count, skipping null and boolean children', () => {
+      render(
+        <Carousel aria-label="Photos">
+          <div>One</div>
+          {null}
+          {false}
+          <div>Two</div>
+        </Carousel>,
+      );
+      const slides = screen.getAllByRole('group');
+      expect(slides).toHaveLength(2);
+      expect(
+        screen.getByRole('group', {name: 'Slide 1 of 2'}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('group', {name: 'Slide 2 of 2'}),
+      ).toBeInTheDocument();
+    });
+
+    it('keeps the container region semantics unchanged around labelled slides', () => {
+      render(
+        <Carousel aria-label="Gallery">
+          <div>One</div>
+          <div>Two</div>
+        </Carousel>,
+      );
+      const region = screen.getByRole('region', {name: 'Gallery'});
+      expect(region).toHaveAttribute('aria-roledescription', 'carousel');
+      const slides = screen.getAllByRole('group');
+      expect(slides).toHaveLength(2);
+      slides.forEach(slide => expect(region).toContainElement(slide));
+    });
+  });
+
   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

package/src/Carousel/Carousel.tsx

@@ -9,7 +9,10 @@
  * @position Horizontal scroll container with fade-edge overflow indication,
  *   optional prev/next buttons on the top layer, scroll-snap, a 1px
  *   visual bleed allowance for child selection indicators, and Shift + wheel
- *   mapping so mouse users can scroll horizontally.
+ *   mapping so mouse users can scroll horizontally. Exposes APG
+ *   carousel semantics: the root is a labelled region with
+ *   aria-roledescription="carousel" and each item wrapper is a group with
+ *   aria-roledescription="slide" named "Slide N of M".
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)
@@ -17,7 +20,14 @@
  * - /packages/cli/templates/blocks/components/Carousel/ (showcase blocks)
  */
 
-import {type ReactNode, useRef, useCallback, useEffect, Children} from 'react';
+import {
+  type ReactNode,
+  useRef,
+  useCallback,
+  useEffect,
+  Children,
+  isValidElement,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   spacingVars,
@@ -31,8 +41,9 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {useLayer} from '../Layer';
 import {useScrollOverflow} from '../hooks/useScrollOverflow';
+import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -156,10 +167,16 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   buttonPillStart: {
-    transform: 'translateX(-50%)',
+    transform: {
+      default: 'translateX(-50%)',
+      ':is([dir="rtl"] *)': 'translateX(50%)',
+    },
   },
   buttonPillEnd: {
-    transform: 'translateX(50%)',
+    transform: {
+      default: 'translateX(50%)',
+      ':is([dir="rtl"] *)': 'translateX(-50%)',
+    },
   },
   buttonHidden: {
     opacity: 0,
@@ -270,6 +287,11 @@ export function Carousel({
   const scrollElRef = useRef<HTMLElement | null>(null);
   const {scrollRef, overflowStart, overflowEnd} = useScrollOverflow();
 
+  // Children.toArray drops null/undefined/boolean children and assigns
+  // stable keys, so slide numbering ("Slide N of M") matches what actually
+  // renders even when some children are conditionally omitted.
+  const slides = Children.toArray(children);
+
   const layer = useLayer({
     mode: 'context',
     lightDismiss: false,
@@ -332,7 +354,11 @@ export function Carousel({
       typeof window.matchMedia === 'function' &&
       window.matchMedia('(prefers-reduced-motion: reduce)').matches;
     el.scrollBy({
-      left: direction * Math.max(amount, itemWidth),
+      // `direction` is the logical intent (-1 = toward content start, +1 =
+      // toward content end). Under RTL the scroll axis is inverted (start is
+      // scrollLeft 0, the end is negative), so flip the physical delta sign.
+      left:
+        (isRtlElement(el) ? -1 : 1) * direction * Math.max(amount, itemWidth),
       behavior: prefersReducedMotion ? 'auto' : 'smooth',
     });
   }, []);
@@ -380,8 +406,23 @@ export function Carousel({
           hasSnap && styles.snap,
           fadeStyle,
         )}>
-        {Children.map(children, child => (
-          <div {...stylex.props(styles.item)}>{child}</div>
+        {slides.map((child, index) => (
+          // APG carousel pattern: each slide container is a group with
+          // aria-roledescription="slide" and an "N of M" accessible name so
+          // ATs announce slide boundaries and position instead of anonymous
+          // generics.
+          <div
+            // eslint-disable-next-line @eslint-react/no-array-index-key -- index fallback only applies to text/number children, which are positional by definition; elements keep their Children.toArray keys
+            key={isValidElement(child) ? child.key : index}
+            role="group"
+            aria-roledescription="slide"
+            aria-label={t('@astryx.carousel.slideLabel', {
+              current: index + 1,
+              total: slides.length,
+            })}
+            {...stylex.props(styles.item)}>
+            {child}
+          </div>
         ))}
       </div>
 
@@ -395,7 +436,11 @@ export function Carousel({
                 !overflowStart && styles.buttonHidden,
               )}>
               <Button
-                icon={<Icon icon="chevronLeft" size="xsm" />}
+                icon={
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <Icon icon="chevronLeft" size="xsm" />
+                  </span>
+                }
                 label={t('@astryx.carousel.scrollLeft')}
                 variant="ghost"
                 size="sm"
@@ -416,7 +461,11 @@ export function Carousel({
                 !overflowEnd && styles.buttonHidden,
               )}>
               <Button
-                icon={<Icon icon="chevronRight" size="xsm" />}
+                icon={
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
+                }
                 label={t('@astryx.carousel.scrollRight')}
                 variant="ghost"
                 size="sm"

package/src/Chat/ChatComposer.doc.mjs

@@ -56,6 +56,13 @@ export const docs = {
       description: 'Visual density.',
       default: "'balanced'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low'",
+      description:
+        "Resting elevation of the composer body. `low` (the default) keeps today's raised look: low at rest, bumping to med on hover / focus. `none` flattens it and draws a border with the same rest / hover / focus treatment as a text input (emphasized border → accent on focus, matching inset rings).",
+      default: "'low'",
+    },
     {
       name: 'drawer',
       type: 'ReactNode',
@@ -102,7 +109,7 @@ export const docs = {
     {
       name: 'input',
       type: 'ReactNode',
-      description: 'Slot: custom input element. Replaces the default textarea. Use ChatComposerInput for trigger menus.',
+      description: 'Slot: custom input element. Replaces the default input. Use ChatComposerInput for trigger menus/tokens, or wire any input (plain textarea, rich editor) to the composition contract via useChatComposerContext(): read value/onChange/onSubmit/canSend and register a focus control on inputControlRef so body-click-to-focus works.',
       slotElements: [
         {
           __element: 'TextInput',
@@ -185,10 +192,11 @@ export const docsZh = {
     placeholder: '输入为空时显示的占位文本。',
     isDisabled: '禁用编写器。',
     density: '视觉密度。',
+    elevation: "编写器主体的静止高度。low（默认）保持当前的抬起外观——静止时 low，悬停/聚焦时升至 med。none 则扁平化。",
     drawer: '插槽：输入上方的可折叠抽屉——附件、上下文标签等。使用 ChatComposerDrawer。',
     headerActions: '插槽：标题左侧操作按钮（附件、提及按钮）。使用仅图标 size="sm" 按钮。',
     headerContext: '插槽：标题右侧上下文信息（上下文窗口使用情况、ProgressBar、辅助文本）。',
-    input: '插槽：自定义输入元素。替换默认文本区域。使用 ChatComposerInput 实现触发菜单。',
+    input: '插槽：自定义输入元素。替换默认输入。使用 ChatComposerInput 实现触发菜单/标记，或通过 useChatComposerContext() 将任意输入（纯 textarea、富文本编辑器）接入组合契约——读取 value/onChange/onSubmit/canSend，并在 inputControlRef 上注册聚焦控制，使点击空白处聚焦生效。',
     footerActions: '插槽：左对齐的页脚操作（模型选择器等）。',
     sendActions: '插槽：发送按钮左侧的操作。',
     sendButton: '插槽：自定义发送按钮。替换默认的发送/停止按钮。',
@@ -210,10 +218,11 @@ export const docsDense = {
     placeholder: 'placeholder when empty',
     isDisabled: 'disabled; use during streaming or unmet prereqs',
     density: 'visual density',
+    elevation: "resting elevation of composer body: low (default; low→med on hover/focus) | none (flat)",
     drawer: 'slot: collapsible drawer above input: attachments, context chips, etc.; use ChatComposerDrawer',
     headerActions: 'slot: left header actions (attach, mention); icon-only sm buttons',
     headerContext: 'slot: right header context info (window usage, ProgressBar, text)',
-    input: 'slot: custom input; replaces default textarea; use ChatComposerInput for triggers',
+    input: 'slot: custom input; replaces default. use ChatComposerInput for triggers/tokens, or wire any input via useChatComposerContext() (value/onChange/onSubmit/canSend + register focus on inputControlRef)',
     footerActions: 'slot: left footer actions (model selector etc)',
     sendActions: 'slot: actions left of send btn',
     sendButton: 'slot: custom send btn; replaces default',

package/src/Chat/ChatComposer.test.tsx

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, fireEvent} from '@testing-library/react';
+import {useEffect, useRef} from 'react';
+import {ChatComposer} from './ChatComposer';
+import {useChatComposerContext} from './ChatContext';
+
+// The composer body — the elevated surface — is the div that wraps the input
+// area (styles.body). A custom `input` slot renders inside the inputArea div,
+// so the body is two ancestors up from the slot marker. Walking from a known
+// marker keeps this independent of StyleX's generated class names.
+function renderBodyClass(elevation?: 'none' | 'low'): string {
+  const {container} = render(
+    <ChatComposer
+      onSubmit={() => {}}
+      elevation={elevation}
+      input={<div data-testid="composer-input-marker" />}
+    />,
+  );
+  const marker = container.querySelector(
+    '[data-testid="composer-input-marker"]',
+  )!;
+  const inputArea = marker.parentElement!;
+  const body = inputArea.parentElement!;
+  return body.className;
+}
+
+describe('ChatComposer elevation', () => {
+  it('applies a distinct body class for each supported level', () => {
+    expect(renderBodyClass('none')).not.toBe(renderBodyClass('low'));
+  });
+
+  it("defaults to 'low' (preserves the raised look)", () => {
+    expect(renderBodyClass(undefined)).toBe(renderBodyClass('low'));
+  });
+});
+
+// A custom input that participates in the composer's composition contract:
+// reads value/submit from the exported context, and registers a focus control
+// so the shell can drive body-click-to-focus without knowing its DOM shape.
+function CustomContextInput({focusSpy}: {focusSpy: () => void}) {
+  const ctx = useChatComposerContext();
+  const ref = useRef<HTMLInputElement>(null);
+  const controlRef = ctx?.inputControlRef;
+  useEffect(() => {
+    if (!controlRef) {
+      return;
+    }
+    controlRef.current = {
+      focus: () => {
+        focusSpy();
+        ref.current?.focus();
+      },
+    };
+    return () => {
+      controlRef.current = null;
+    };
+  }, [controlRef, focusSpy]);
+  return (
+    <input
+      ref={ref}
+      data-testid="custom-input"
+      value={ctx?.value ?? ''}
+      placeholder={ctx?.placeholder}
+      disabled={ctx?.isDisabled}
+      onChange={e => ctx?.onChange(e.target.value)}
+    />
+  );
+}
+
+describe('ChatComposer input composition contract', () => {
+  it('exposes value/onChange/placeholder/isDisabled to a custom input via context', () => {
+    const {getByTestId} = render(
+      <ChatComposer
+        onSubmit={() => {}}
+        value="hello"
+        placeholder="Say something"
+        isDisabled
+        input={<CustomContextInput focusSpy={() => {}} />}
+      />,
+    );
+    const input = getByTestId('custom-input') as HTMLInputElement;
+    expect(input.value).toBe('hello');
+    expect(input.placeholder).toBe('Say something');
+    expect(input.disabled).toBe(true);
+  });
+
+  it('focuses a custom input via its registered control on body click', () => {
+    const focusSpy = vi.fn();
+    const {getByTestId} = render(
+      <ChatComposer
+        onSubmit={() => {}}
+        input={<CustomContextInput focusSpy={focusSpy} />}
+      />,
+    );
+    const marker = getByTestId('custom-input');
+    const body = marker.parentElement!.parentElement!;
+    fireEvent.click(body);
+    expect(focusSpy).toHaveBeenCalled();
+  });
+
+  it('falls back to focusing a bare textarea when no control is registered', () => {
+    const {getByTestId} = render(
+      <ChatComposer
+        onSubmit={() => {}}
+        input={<textarea data-testid="bare-textarea" />}
+      />,
+    );
+    const textarea = getByTestId('bare-textarea') as HTMLTextAreaElement;
+    const body = textarea.parentElement!.parentElement!;
+    fireEvent.click(body);
+    expect(document.activeElement).toBe(textarea);
+  });
+});

package/src/Chat/ChatComposer.tsx

@@ -40,6 +40,7 @@ import {
   shadowVars,
   durationVars,
   easeVars,
+  borderVars,
   typeScaleVars,
   typographyVars,
 } from '../theme/tokens.stylex';
@@ -47,6 +48,7 @@ import {mergeProps} from '../utils';
 import {Icon} from '../Icon';
 import {ChatComposerInput} from './ChatComposerInput';
 import {ChatComposerContext} from './ChatContext';
+import type {ChatComposerInputControl} from './ChatContext';
 import {ChatSendButton} from './ChatSendButton';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -83,6 +85,14 @@ export interface ChatComposerProps extends Omit<
   isDisabled?: boolean;
   /** Density variant */
   density?: ChatComposerDensity;
+  /**
+   * Resting elevation of the composer body. `low` (the default) keeps today's
+   * raised look — low at rest, bumping to med on hover / focus. `none` flattens
+   * it and draws a border with the same rest / hover / focus treatment as a
+   * text input (emphasized border → accent on focus, with matching inset rings).
+   * @default 'low'
+   */
+  elevation?: 'none' | 'low';
 
   // --- Slot props ---
 
@@ -143,14 +153,7 @@ const styles = stylex.create({
     borderRadius: 'var(--_chat-composer-radius)',
     backgroundColor: colorVars['--color-background-popover'],
     cursor: 'text',
-    boxShadow: {
-      default: shadowVars['--shadow-low'],
-      ':hover': {'@media (hover: hover)': shadowVars['--shadow-med']},
-    },
-    transition: `box-shadow ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
-    ':focus-within': {
-      boxShadow: shadowVars['--shadow-med'],
-    },
+    transition: `box-shadow ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}, border-color ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
   },
   header: {
     display: 'flex',
@@ -247,11 +250,56 @@ const styles = stylex.create({
     color: colorVars['--color-text-yellow'],
   },
   compact: {
-    padding: spacingVars['--spacing-2'],
+    // Override the padding var (not the `padding` property) so both the base
+    // body padding and the border-inset calc in elevationStyles.none pick up
+    // the compact value. Scoped to the body element, so the status bar (which
+    // reads the var from root) keeps its own padding.
+    '--_chat-composer-padding': spacingVars['--spacing-2'],
     gap: spacingVars['--spacing-1'],
   },
 });
 
+// Resting elevation for the composer body, narrowed to two steps.
+// - `low` (default) preserves today's look: low at rest, bumping to med on
+//   hover / focus-within (a CSS-only interaction state the component owns).
+// - `none` is flat; depth comes from a border + inset rings instead. The
+//   border is drawn *inside* the padding — its width is subtracted from every
+//   side (like Card) so total inset (border + padding) equals the elevated
+//   case and content geometry is unchanged. Border color, hover, and focus
+//   states mirror TextInput (shared `inputWrapperStyles.base` treatment):
+//   emphasized border at rest → accent on focus-within, with the same inset
+//   shadow rings on hover and focus.
+const elevationStyles = stylex.create({
+  low: {
+    boxShadow: {
+      default: shadowVars['--shadow-low'],
+      ':hover': {'@media (hover: hover)': shadowVars['--shadow-med']},
+    },
+    ':focus-within': {
+      boxShadow: shadowVars['--shadow-med'],
+    },
+  },
+  none: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    // Draw the border *inside* the padding — subtract its width from the body
+    // padding (like Card's withBorder) so total inset (border + padding) equals
+    // the elevated case and content geometry is unchanged.
+    padding: `calc(var(--_chat-composer-padding) - ${borderVars['--border-width']})`,
+    boxShadow: {
+      default: 'none',
+      ':hover:not(:focus-within)': {
+        '@media (hover: hover)': `inset 0px 0px 0px 2px color-mix(in srgb, ${colorVars['--color-border-emphasized']} 30%, transparent)`,
+      },
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -280,6 +328,7 @@ export function ChatComposer(props: ChatComposerProps) {
     placeholder: placeholderFromProps,
     isDisabled = false,
     density = 'balanced',
+    elevation = 'low',
     drawer,
     headerActions,
     headerContext,
@@ -325,6 +374,11 @@ export function ChatComposer(props: ChatComposerProps) {
 
   const bodyRef = useRef<HTMLDivElement>(null);
 
+  // Input slot registers its focus (and future) control here so the shell can
+  // drive it without knowing its DOM shape. Stable ref — safe in the memoized
+  // context value.
+  const inputControlRef = useRef<ChatComposerInputControl | null>(null);
+
   const handleBodyClick = useCallback((e: MouseEvent<HTMLDivElement>) => {
     // Focus the input when clicking empty space in the body.
     // Skip if the click target is a button, link, or interactive element.
@@ -336,6 +390,14 @@ export function ChatComposer(props: ChatComposerProps) {
     ) {
       return;
     }
+    // Prefer the input's registered control (works for any input shape,
+    // including editors whose focusable node isn't a bare
+    // contenteditable/textarea). Fall back to a DOM query so uninstrumented
+    // custom inputs still get click-to-focus.
+    if (inputControlRef.current) {
+      inputControlRef.current.focus();
+      return;
+    }
     const editable = bodyRef.current?.querySelector<HTMLElement>(
       '[contenteditable="true"], textarea',
     );
@@ -370,6 +432,7 @@ export function ChatComposer(props: ChatComposerProps) {
       isStopShown,
       canSend,
       onStop,
+      inputControlRef,
     }),
     [
       currentValue,
@@ -402,6 +465,7 @@ export function ChatComposer(props: ChatComposerProps) {
           onClick={handleBodyClick}
           {...stylex.props(
             styles.body,
+            elevationStyles[elevation],
             density === 'compact' && styles.compact,
             xstyle,
           )}>

package/src/Chat/ChatComposerDrawer.test.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {ChatComposerDrawer} from './ChatComposerDrawer';
+
+describe('ChatComposerDrawer', () => {
+  it('links the toggle to the drawer content via aria-controls', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments">
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    const controlsId = toggle.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real content region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByText('Drawer content'));
+  });
+
+  it('keeps aria-controls resolvable while collapsed (content stays mounted)', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments" defaultIsCollapsed>
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    const controlsId = toggle.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByText('Drawer content'));
+  });
+
+  it('toggles aria-expanded when the toggle is activated', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments">
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    fireEvent.click(toggle);
+    expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+
+    fireEvent.click(screen.getByRole('button', {name: /Attachments/}));
+    expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(
+      'aria-expanded',
+      'true',
+    );
+  });
+});

package/src/Chat/ChatComposerDrawer.tsx

@@ -9,13 +9,15 @@
  * @position Collapsible drawer panel for ChatComposer.
  *   Supports expanded (full content) and collapsed (count + label) states
  *   with fade animation and grid-template-rows height transition.
+ *   The collapse toggle exposes aria-expanded + aria-controls linking it to
+ *   the content region (disclosure pattern).
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /packages/cli/templates/blocks/components/ChatComposerDrawer/ (block examples)
  */
 
-import {useState, type ReactNode} from 'react';
+import {useId, useState, type ReactNode} from 'react';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -240,6 +242,12 @@ export function ChatComposerDrawer({
 
   const canCollapse = count != null;
 
+  // Links the toggle to the region it shows/hides so assistive tech can move
+  // from the button to its controlled content (disclosure pattern). The
+  // content stays mounted while collapsed (hidden via the grid-row collapse),
+  // so the reference always resolves.
+  const contentId = useId();
+
   const toggle = () => {
     const next = !isCollapsed;
     if (!isControlled) {
@@ -271,6 +279,7 @@ export function ChatComposerDrawer({
           role="button"
           tabIndex={0}
           aria-expanded={!isCollapsed}
+          aria-controls={contentId}
           aria-label={
             isCollapsed
               ? t('@astryx.chatComposerDrawer.expand', {label})
@@ -301,6 +310,7 @@ export function ChatComposerDrawer({
       )}
 
       <div
+        id={contentId}
         {...stylex.props(
           styles.contentGrid,
           canCollapse && isCollapsed && styles.contentGridCollapsed,

package/src/Chat/ChatComposerInput.doc.mjs

@@ -80,6 +80,11 @@ export const docs = {
       type: '(value: string) => void',
       description: 'Called when the user presses Enter without Shift. The serialized value includes token placeholders.',
     },
+    {
+      name: 'onKeyDown',
+      type: '(event) => void',
+      description: 'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected; Enter never submits mid-composition.',
+    },
   ],
 };
 
@@ -102,6 +107,7 @@ export const docsZh = {
     onPaste: '粘贴文本时调用。用于拦截或转换粘贴内容。',
     onFiles: '粘贴或拖放文件到输入时调用。用于处理附件。',
     onSubmit: '用户不按 Shift 按 Enter 时调用。序列化值包含标记占位符。',
+    onKeyDown: '在内置 Enter/历史处理之前（在打开的触发菜单之后）调用的按键处理器。平台特定按键的接缝：调用 event.preventDefault() 可抑制默认提交（例如触控键盘上插入换行），或自行处理事件以添加行为（例如 Cmd/Ctrl+Enter 提交）。始终尊重输入法组字状态——组字过程中 Enter 永不提交。',
   },
 };
 
@@ -124,5 +130,6 @@ export const docsDense = {
     onPaste: 'paste handler; intercept/transform pasted content',
     onFiles: 'file paste/drop handler; use for attachments',
     onSubmit: 'Enter w/o Shift handler; serialized value includes token placeholders',
+    onKeyDown: 'keydown handler before built-in Enter/history (after trigger menu); preventDefault() to suppress default submit (touch newline) or act on event to add behavior (Cmd/Ctrl+Enter). IME composition always respected',
   },
 };