@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/Carousel/Carousel.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import {Carousel} from './Carousel';
 
 // Mock ResizeObserver (not available in jsdom)
@@ -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
@@ -111,4 +164,99 @@ describe('Carousel', () => {
     expect(left).toBeDisabled();
     expect(right).toBeDisabled();
   });
+
+  describe('Shift + wheel horizontal scroll', () => {
+    // jsdom doesn't lay out elements, so we fake an overflowing scroll
+    // container and capture scrollBy calls.
+    function getScroller() {
+      const region = screen.getByRole('region');
+      return region.firstElementChild as HTMLElement;
+    }
+
+    function makeOverflowing(el: HTMLElement) {
+      Object.defineProperty(el, 'scrollWidth', {
+        value: 500,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'clientWidth', {
+        value: 200,
+        configurable: true,
+      });
+    }
+
+    it('maps Shift + vertical wheel to horizontal scroll', () => {
+      render(
+        <Carousel aria-label="Wheel">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller);
+      const scrollBy = vi.fn();
+      scroller.scrollBy = scrollBy;
+
+      fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
+
+      expect(scrollBy).toHaveBeenCalledWith({left: 120, behavior: 'auto'});
+    });
+
+    it('does not translate wheel without Shift held', () => {
+      render(
+        <Carousel aria-label="Wheel">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller);
+      const scrollBy = vi.fn();
+      scroller.scrollBy = scrollBy;
+
+      fireEvent.wheel(scroller, {shiftKey: false, deltaY: 120, deltaX: 0});
+
+      expect(scrollBy).not.toHaveBeenCalled();
+    });
+
+    it('leaves native horizontal wheel deltas alone', () => {
+      // Trackpads emit deltaX directly — don't double-handle those.
+      render(
+        <Carousel aria-label="Wheel">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller);
+      const scrollBy = vi.fn();
+      scroller.scrollBy = scrollBy;
+
+      fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 40});
+
+      expect(scrollBy).not.toHaveBeenCalled();
+    });
+
+    it('does not intercept when there is no horizontal overflow', () => {
+      render(
+        <Carousel aria-label="Wheel">
+          <div>Item 1</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      Object.defineProperty(scroller, 'scrollWidth', {
+        value: 200,
+        configurable: true,
+      });
+      Object.defineProperty(scroller, 'clientWidth', {
+        value: 200,
+        configurable: true,
+      });
+      const scrollBy = vi.fn();
+      scroller.scrollBy = scrollBy;
+
+      fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
+
+      expect(scrollBy).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/Carousel/Carousel.tsx

@@ -7,8 +7,12 @@
  * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
  * @output Exports Carousel component
  * @position Horizontal scroll container with fade-edge overflow indication,
- *   optional prev/next buttons on the top layer, scroll-snap, and a 1px
- *   visual bleed allowance for child selection indicators.
+ *   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. 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)
@@ -16,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,
@@ -269,6 +280,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,
@@ -290,6 +306,31 @@ export function Carousel({
     [scrollRef],
   );
 
+  // Map Shift + vertical wheel to horizontal scroll. Trackpads emit
+  // horizontal deltas natively, but a standard mouse only produces deltaY —
+  // so mouse users can't wheel-scroll a horizontal container. Shift + wheel
+  // is the long-established convention for horizontal scroll containers; we
+  // honor it by translating the vertical delta into a horizontal scroll.
+  //
+  // Only kicks in when Shift is held and the wheel is purely vertical
+  // (deltaX === 0), so native trackpad horizontal scrolling is untouched.
+  const handleWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {
+    if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {
+      return;
+    }
+    const el = scrollElRef.current;
+    if (!el) {
+      return;
+    }
+    // Nothing to scroll horizontally — let the event fall through so the page
+    // can scroll as it normally would.
+    if (el.scrollWidth <= el.clientWidth) {
+      return;
+    }
+    event.preventDefault();
+    el.scrollBy({left: event.deltaY, behavior: 'auto'});
+  }, []);
+
   const scrollBy = useCallback((direction: -1 | 1) => {
     const el = scrollElRef.current;
     if (!el) {
@@ -346,6 +387,7 @@ export function Carousel({
       <div
         ref={composedRef}
         tabIndex={0}
+        onWheel={handleWheel}
         {...stylex.props(
           styles.scroller,
           gapStyles[gap],
@@ -353,8 +395,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>
 

package/src/Chat/Chat.doc.mjs

@@ -80,7 +80,7 @@ export const docs = {
       { name: 'Scroll-to-bottom button', required: false, description: 'Appears when the user scrolls up or new messages arrive. Defaults to ChatLayoutScrollButton; pass null to hide or a custom element to override.' },
       { name: 'Composer', required: true, description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer.' },
       { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use EmptyState for a consistent look.' },
-      { name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically Avatar with size="small". Hidden for system messages.' },
+      { name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically Avatar with size="md". Hidden for system messages.' },
       { name: 'Name', required: false, description: 'Sender name above the message body. Place on the bubble when using bubbles, or on the message wrapper for raw content.' },
       { name: 'Content', required: true, description: 'The message body: one or more ChatMessageBubble elements, or any free-form ReactNode like images or tool calls.' },
       { name: 'Metadata', required: false, description: 'Timestamp, delivery status, and footer actions below the message. Place on the last bubble or on the message wrapper.' },

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',
@@ -185,6 +192,7 @@ export const docsZh = {
     placeholder: '输入为空时显示的占位文本。',
     isDisabled: '禁用编写器。',
     density: '视觉密度。',
+    elevation: "编写器主体的静止高度。low（默认）保持当前的抬起外观——静止时 low，悬停/聚焦时升至 med。none 则扁平化。",
     drawer: '插槽：输入上方的可折叠抽屉——附件、上下文标签等。使用 ChatComposerDrawer。',
     headerActions: '插槽：标题左侧操作按钮（附件、提及按钮）。使用仅图标 size="sm" 按钮。',
     headerContext: '插槽：标题右侧上下文信息（上下文窗口使用情况、ProgressBar、辅助文本）。',
@@ -210,6 +218,7 @@ 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)',

package/src/Chat/ChatComposer.test.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render} from '@testing-library/react';
+import {ChatComposer} from './ChatComposer';
+
+// 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'));
+  });
+});

package/src/Chat/ChatComposer.tsx

@@ -40,6 +40,7 @@ import {
   shadowVars,
   durationVars,
   easeVars,
+  borderVars,
   typeScaleVars,
   typographyVars,
 } from '../theme/tokens.stylex';
@@ -83,6 +84,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 +152,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 +249,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 +327,7 @@ export function ChatComposer(props: ChatComposerProps) {
     placeholder: placeholderFromProps,
     isDisabled = false,
     density = 'balanced',
+    elevation = 'low',
     drawer,
     headerActions,
     headerContext,
@@ -402,6 +450,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',
   },
 };