@astryxdesign/core 0.1.8 → 0.1.9

package/src/Calendar/Calendar.test.tsx

@@ -16,7 +16,10 @@ import {getButton} from '../__tests__/fastRoleQueries';
 import * as stylex from '@stylexjs/stylex';
 import {Calendar} from './Calendar';
 import type {CalendarHandle} from './Calendar';
+import type {ISODateString} from './Calendar';
 import {calendarStyles} from './styles';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -881,4 +884,194 @@ describe('Calendar', () => {
       expect(screen.getByText('February 2026')).toBeInTheDocument();
     });
   });
+
+
+  // ─── Day-cell marker theming (#4286) ─────────────────────────
+  describe('day-cell marker theme state', () => {
+    // Tests use the real "today" (as the existing aria-current tests do) since
+    // Calendar derives it internally. Helpers pin the exact ISO strings.
+    function todayISO(): ISODateString {
+      const n = new Date();
+      return `${n.getFullYear()}-${String(n.getMonth() + 1).padStart(2, '0')}-${String(n.getDate()).padStart(2, '0')}` as ISODateString;
+    }
+    function isoOffsetFromToday(deltaDays: number): ISODateString {
+      const n = new Date();
+      n.setDate(n.getDate() + deltaDays);
+      return `${n.getFullYear()}-${String(n.getMonth() + 1).padStart(2, '0')}-${String(n.getDate()).padStart(2, '0')}` as ISODateString;
+    }
+    function todayCell(): HTMLElement {
+      const el = document.querySelector<HTMLElement>(
+        `button[data-date="${todayISO()}"]`,
+      );
+      expect(el).not.toBeNull();
+      return el as HTMLElement;
+    }
+
+    it('reflects marker="today-only" for a plain today cell (no selection)', () => {
+      render(<Calendar />);
+      const cell = todayCell();
+      expect(cell).toHaveAttribute('data-marker', 'today-only');
+      expect(cell).toHaveAttribute('data-today', 'today');
+      expect(cell).not.toHaveAttribute('data-selected');
+      expect(cell).not.toHaveAttribute('data-in-range');
+    });
+
+    it('reflects marker="today-in-range" when today is strictly inside a range', () => {
+      render(
+        <Calendar
+          mode="range"
+          value={{start: isoOffsetFromToday(-2), end: isoOffsetFromToday(2)}}
+        />,
+      );
+      const cell = todayCell();
+      // Today is inside the range but not an endpoint: the today-in-range ring
+      // is shown, so `marker` reflects that compound state precisely.
+      expect(cell).toHaveAttribute('data-marker', 'today-in-range');
+      expect(cell).toHaveAttribute('data-in-range', 'in-range');
+      expect(cell).not.toHaveAttribute('data-selected');
+    });
+
+    it('shows no marker state when today is the single-selected date', () => {
+      render(<Calendar mode="single" value={todayISO()} />);
+      const cell = todayCell();
+      // A single-mode selected cell shows no ring by default — `marker` is
+      // absent, while `selected` (which owns the selected treatment) is present.
+      expect(cell).not.toHaveAttribute('data-marker');
+      expect(cell).toHaveAttribute('data-selected', 'selected');
+      expect(cell).toHaveAttribute('data-today', 'today');
+    });
+
+    it('preserves the today-in-range ring on a today range endpoint', () => {
+      render(
+        <Calendar
+          mode="range"
+          value={{start: todayISO(), end: isoOffsetFromToday(3)}}
+        />,
+      );
+      const cell = todayCell();
+      // A range endpoint is NOT `isSelected` (that flag is single-mode only),
+      // so by default the today-in-range ring IS drawn on a today endpoint
+      // alongside the endpoint styling. `marker` mirrors that exactly — this
+      // asserts the default rendering is preserved, byte-for-byte.
+      expect(cell).toHaveAttribute('data-marker', 'today-in-range');
+      expect(cell).toHaveAttribute('data-in-range', 'in-range');
+    });
+
+    it('omits the marker state for non-today cells', () => {
+      render(<Calendar />);
+      const other = document.querySelector(
+        `button[data-date="${isoOffsetFromToday(1)}"]`,
+      );
+      // Guard against the +1 day landing in an adjacent month with outside days
+      // hidden; if present it must carry no marker.
+      if (other) {
+        expect(other).not.toHaveAttribute('data-marker');
+      }
+    });
+
+    it('exposes the marker states as themeable defineTheme targets', () => {
+      // jsdom can't resolve the @layer cascade, so the DOM-reflection tests
+      // above cover that the right state renders; this asserts the state is
+      // reachable by a theme via the sanctioned defineTheme channel.
+      const theme = defineTheme({
+        name: 'calendar-marker-test',
+        components: {
+          'calendar-day': {
+            'marker:today-only': {
+              boxShadow: 'inset 0 0 0 2px var(--color-accent)',
+            },
+            'marker:today-in-range': {
+              boxShadow: 'inset 0 0 0 2px var(--color-text-primary)',
+            },
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-calendar-day.today-only');
+      expect(css).toContain('.astryx-calendar-day.today-in-range');
+      expect(css).toContain('box-shadow: inset 0 0 0 2px var(--color-accent)');
+      expect(css).toContain(
+        'box-shadow: inset 0 0 0 2px var(--color-text-primary)',
+      );
+    });
+  });
+
+  // ─── Theming targets ─────────────────────────────────────────
+  describe('theming targets', () => {
+    it('renders the astryx-calendar-nav target on both month-nav buttons', () => {
+      render(<Calendar focusDate="2026-01-01" />);
+
+      const prev = getButton('Previous month');
+      const next = getButton('Next month');
+
+      // Dedicated, stable theme target — scoped to the nav controls, not the
+      // global astryx-button handle that hits every Button in the app.
+      expect(prev).toHaveClass('astryx-calendar-nav');
+      expect(next).toHaveClass('astryx-calendar-nav');
+
+      // Direction is reflected so a theme can target one arrow alone.
+      expect(prev).toHaveAttribute('data-nav', 'prev');
+      expect(next).toHaveAttribute('data-nav', 'next');
+    });
+
+    it('reflects the disabled nav state as a data attribute at the range edges', () => {
+      // Clamp navigation so "Previous month" is disabled and "Next" is not.
+      render(
+        <Calendar focusDate="2026-01-15" min="2026-01-01" max="2026-03-31" />,
+      );
+
+      const prev = getButton('Previous month');
+      const next = getButton('Next month');
+
+      expect(prev).toHaveAttribute('data-disabled', 'disabled');
+      expect(next).not.toHaveAttribute('data-disabled');
+    });
+
+    it('keeps the default nav rendering unchanged (still a ghost icon button)', () => {
+      render(<Calendar focusDate="2026-01-01" />);
+
+      // The new target is additive — the nav still carries the stock Button
+      // classes, so default appearance is preserved.
+      const prev = getButton('Previous month');
+      expect(prev).toHaveClass('astryx-button');
+      expect(prev).toHaveClass('ghost');
+      expect(prev.tagName).toBe('BUTTON');
+    });
+
+    it('renders the astryx-calendar-day target with its reflected states', () => {
+      render(
+        <Calendar mode="single" value="2026-01-15" focusDate="2026-01-01" />,
+      );
+
+      const selected = getDayButton(15);
+      expect(selected).toHaveClass('astryx-calendar-day');
+      expect(selected).toHaveAttribute('data-selected', 'selected');
+
+      // A non-selected weekday cell still carries the base target and no
+      // selected/today reflection.
+      const plain = getDayButton(20);
+      expect(plain).toHaveClass('astryx-calendar-day');
+      expect(plain).not.toHaveAttribute('data-selected');
+    });
+
+    it('exposes calendar-nav as a themeable defineTheme target', () => {
+      // The generated CSS is what proves the target is reachable by a theme:
+      // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+      // above and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'calendar-nav-test',
+        components: {
+          'calendar-nav': {
+            base: {color: 'var(--color-accent)'},
+            'nav:next': {backgroundColor: 'var(--color-accent-muted)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-calendar-nav {');
+      expect(css).toContain('color: var(--color-accent)');
+      expect(css).toContain('.astryx-calendar-nav.next');
+      expect(css).toContain('background-color: var(--color-accent-muted)');
+    });
+  });
 });

package/src/Calendar/Calendar.tsx

@@ -452,6 +452,10 @@ export function Calendar({ref, ...props}: CalendarProps) {
       {/* Header with navigation */}
       <div {...stylex.props(calendarStyles.header)}>
         <Button
+          {...themeProps('calendar-nav', {
+            nav: 'prev',
+            disabled: !canNavigatePrevious ? 'disabled' : null,
+          })}
           label={t('@astryx.calendar.previousMonth')}
           variant="ghost"
           icon={
@@ -472,6 +476,10 @@ export function Calendar({ref, ...props}: CalendarProps) {
         </span>
 
         <Button
+          {...themeProps('calendar-nav', {
+            nav: 'next',
+            disabled: !canNavigateNext ? 'disabled' : null,
+          })}
           label={t('@astryx.calendar.nextMonth')}
           variant="ghost"
           icon={
@@ -941,6 +949,21 @@ function DayCell({
   });
 
   const endpoint = isEndpoint(state);
+
+  // The day's focus-ring treatment, derived once so the reflected `marker`
+  // theme state and the StyleX ring styles below share a single source of
+  // truth. `state.isSelected` is single-select only, so a range endpoint that
+  // is today still qualifies for the today-in-range ring (unchanged prior
+  // behavior).
+  const showsTodayRing = state.isToday && !state.isSelected && !state.isInRange;
+  const showsTodayInRangeRing =
+    state.isToday && !state.isSelected && state.isInRange;
+  const markerState: 'today-only' | 'today-in-range' | null = showsTodayRing
+    ? 'today-only'
+    : showsTodayInRangeRing
+      ? 'today-in-range'
+      : null;
+
   const rangeRounding = computeRangeRounding(state, {
     prevInRange: neighbors.prevInRange,
     nextInRange: neighbors.nextInRange,
@@ -1010,28 +1033,27 @@ function DayCell({
             today: state.isToday ? 'today' : null,
             disabled: state.effectivelyDisabled ? 'disabled' : null,
             'in-range': state.isInRange ? 'in-range' : null,
+            // `marker` reflects the day's *actual* focus-ring treatment as a
+            // single compound state, so a theme can target exactly the states
+            // the ring is drawn under without needing `:not()` in the theme
+            // key. It is null unless a ring is shown:
+            //   'today-only'     → today, not single-selected, not in a range
+            //   'today-in-range' → today, not single-selected, inside a range
+            // `isSelected` here is single-select only (see computeDayCellState),
+            // so a today range endpoint still shows the today-in-range ring —
+            // `marker` mirrors the StyleX conditions below exactly, preserving
+            // the default rendering.
+            marker: markerState,
           }),
           stylex.props(
             dayCellStyles.day,
             dayCellTheme.day,
             isOutside && dayCellStyles.dayOutside,
             isOutside && dayCellTheme.dayOutside,
-            state.isToday &&
-              !state.isSelected &&
-              !state.isInRange &&
-              dayCellStyles.dayToday,
-            state.isToday &&
-              !state.isSelected &&
-              !state.isInRange &&
-              dayCellTheme.dayToday,
-            state.isToday &&
-              !state.isSelected &&
-              state.isInRange &&
-              dayCellStyles.dayTodayInRange,
-            state.isToday &&
-              !state.isSelected &&
-              state.isInRange &&
-              dayCellTheme.dayTodayInRange,
+            showsTodayRing && dayCellStyles.dayToday,
+            showsTodayRing && dayCellTheme.dayToday,
+            showsTodayInRangeRing && dayCellStyles.dayTodayInRange,
+            showsTodayInRangeRing && dayCellTheme.dayTodayInRange,
             endpoint && dayCellStyles.daySelected,
             endpoint && dayCellTheme.daySelected,
             state.effectivelyDisabled && dayCellStyles.dayDisabled,

package/src/Calendar/dayCellUtils.test.ts

@@ -45,6 +45,11 @@ describe('computeDayCellState', () => {
     expect(state.isToday).toBe(false);
   });
 
+  it('does not identify an outside day as today', () => {
+    const state = computeDayCellState(makeInput({isOutside: true}));
+    expect(state.isToday).toBe(false);
+  });
+
   it('identifies selected day in single mode', () => {
     const state = computeDayCellState(
       makeInput({selectedDate: plainDateFromISO('2024-03-15')}),

package/src/Calendar/dayCellUtils.ts

@@ -56,7 +56,7 @@ export function computeDayCellState(input: DayCellStateInput): DayCellState {
 
   return {
     effectivelyDisabled: isDisabled || isOutside,
-    isToday: plainDateIsEqual(date, today),
+    isToday: !isOutside && plainDateIsEqual(date, today),
     isSelected: !!(
       !isOutside &&
       mode === 'single' &&

package/src/Card/Card.doc.mjs

@@ -67,6 +67,13 @@ export const docs = {
         'Background color variant. `default` uses the standard card background. `transparent` drops the background entirely. `muted` uses the muted background for de-emphasised cards. The non-semantic variants use the corresponding `--color-background-<name>` token.',
       default: "'default'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. `none` is flat; `low`/`med`/`high` map to the shadow token scale. Raise a card only when it needs to float above surrounding content.',
+      default: "'none'",
+    },
   ],
   playground: {
     defaults: {
@@ -127,6 +134,7 @@ export const docsZh = {
     {name: 'minHeight', type: 'SizeValue', description: '卡片最小高度。'},
     {name: 'children', type: 'ReactNode', description: '在卡片内部渲染的内容。'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。', default: '4'},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平；`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},
   ],
   theming: {
     container: true,
@@ -170,5 +178,6 @@ export const docsDense = {
     children: 'content inside card',
     padding: 'internal padding via spacing scale',
     variant: 'background color variant; `default` = standard card bg, `transparent` = no background at all, `muted` = muted bg for de-emphasised cards; non-semantic variants use the corresponding `--color-background-<name>` token',
+    elevation: 'resting shadow depth: none (flat) | low | med | high (shadow token scale). Raise only to float above content.',
   },
 };

package/src/Card/Card.test.tsx

@@ -17,11 +17,29 @@ describe('Card', () => {
   });
 
   it('renders transparent variant with variant class', () => {
-    const {container} = render(
-      <Card variant="transparent">Content</Card>,
-    );
+    const {container} = render(<Card variant="transparent">Content</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
     expect(root.className).toContain('transparent');
   });
+
+  it('applies a distinct class for each elevation level', () => {
+    const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+      const {container} = render(<Card elevation={elevation}>C</Card>);
+      return container.firstElementChild!.className;
+    };
+    const none = classFor('none');
+    const low = classFor('low');
+    const med = classFor('med');
+    const high = classFor('high');
+    expect(new Set([none, low, med, high]).size).toBe(4);
+  });
+
+  it('defaults to flat (elevation none) — same class as explicit none', () => {
+    const {container: defaultContainer} = render(<Card>C</Card>);
+    const {container: noneContainer} = render(<Card elevation="none">C</Card>);
+    expect(defaultContainer.firstElementChild!.className).toBe(
+      noneContainer.firstElementChild!.className,
+    );
+  });
 });

package/src/Card/Card.tsx

@@ -17,7 +17,12 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {borderVars, colorVars, radiusVars} from '../theme/tokens.stylex';
+import {
+  borderVars,
+  colorVars,
+  radiusVars,
+  shadowVars,
+} from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
 import {
@@ -27,7 +32,7 @@ import {
   containerPaddingBlockEndVarStyles,
   spacingStepToToken,
 } from '../Layout/padding.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -73,6 +78,13 @@ const styles = stylex.create({
     '--_card-radius': radiusVars['--radius-container'],
     borderRadius: 'var(--_card-radius)',
     overflow: 'clip',
+    // Resting elevation is set via --_card-elevation (see elevationStyles).
+    // The shadow list also reads --_card-ring so composing surfaces — e.g.
+    // SelectableCard's inset selection ring — can layer their own shadow
+    // alongside elevation instead of clobbering the single box-shadow property.
+    // Unset vars fall back to a transparent no-op shadow.
+    boxShadow:
+      'var(--_card-ring, 0 0 transparent), var(--_card-elevation, 0 0 transparent)',
   },
   // The border is drawn *inside* the padding — its width is subtracted from
   // each side — so total inset (border + padding) equals the padding token
@@ -135,6 +147,18 @@ const variantStyles = stylex.create({
   },
 });
 
+// Elevation → shadow-token map. Sets the private --_card-elevation variable
+// (not box-shadow directly) so it composes with --_card-ring in the shadow
+// list above — a selection ring and a resting elevation coexist without one
+// overwriting the other. 'none' is a transparent no-op (not the CSS literal
+// `none`, which would be invalid inside the comma-separated shadow list).
+const elevationStyles = stylex.create({
+  none: {'--_card-elevation': '0 0 transparent'},
+  low: {'--_card-elevation': shadowVars['--shadow-low']},
+  med: {'--_card-elevation': shadowVars['--shadow-med']},
+  high: {'--_card-elevation': shadowVars['--shadow-high']},
+});
+
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
   sizing: (
@@ -208,6 +232,13 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
    * @default 'default'
    */
   variant?: CardVariant;
+
+  /**
+   * Resting elevation — the shadow depth the card sits at.
+   * `none` is flat; `low`/`med`/`high` map to the shadow token scale.
+   * @default 'none'
+   */
+  elevation?: Elevation;
 }
 
 /**
@@ -252,6 +283,7 @@ export function Card({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   xstyle,
   className,
   style,
@@ -274,6 +306,7 @@ export function Card({
         stylex.props(
           styles.card,
           variantStyles[variant],
+          elevationStyles[elevation],
           hasFixedHeight && styles.scrollable,
           dynamicStyles.sizing(
             width ?? null,

package/src/Carousel/Carousel.doc.mjs

@@ -91,6 +91,7 @@ export const docsDense = {
       {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
       {guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
       {guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
+      {guidance: true, description: 'Trust built-in navigation: trackpad users swipe horizontally, mouse users hold Shift + wheel to move through items.'},
       {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.'},

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,
@@ -270,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,
@@ -380,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/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',