@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/locales/pseudo.json

@@ -317,6 +317,21 @@
   "@astryx.table.sort.clear": {
     "defaultMessage": "⟦Çłéàř šóřţ⟧"
   },
+  "@astryx.table.sort.direction.ascending": {
+    "defaultMessage": "⟦àšçéñðíñĝ⟧"
+  },
+  "@astryx.table.sort.direction.descending": {
+    "defaultMessage": "⟦ðéšçéñðíñĝ⟧"
+  },
+  "@astryx.table.sort.sortBy": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}⟧"
+  },
+  "@astryx.table.sort.sortedBy": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}, šóřţéð {direction}⟧"
+  },
+  "@astryx.table.sort.sortedByWithPriority": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}, šóřţéð {direction}, þříóříţý {rank, number} óƒ {total, number}⟧"
+  },
   "@astryx.toast.dismiss": {
     "defaultMessage": "⟦Ðíšɱíšš ñóţíƒíçàţíóñ⟧"
   },
@@ -542,6 +557,12 @@
   "@astryx.tableRowExpansion.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.tableTree.collapseRow": {
+    "defaultMessage": "⟦Çółłàþšé řóŵ⟧"
+  },
+  "@astryx.tableTree.expandRow": {
+    "defaultMessage": "⟦Éẋþàñð řóŵ⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.7",
+  "version": "0.1.8-canary.c5fa19b",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -636,6 +636,7 @@
   "files": [
     "dist",
     "src",
+    "scripts/postinstall.mjs",
     "locales",
     "docs.mjs",
     "groups.doc.mjs",
@@ -662,6 +663,7 @@
     "intl-messageformat": "^11.2.9"
   },
   "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
     "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
     "build:i18n": "node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",

package/scripts/postinstall.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file @astryxdesign/core postinstall — nudge to run `npx @astryxdesign/cli init`.
+ *
+ * Enforcement layer 1 of making `astryx init` foolproof: when the design system
+ * is installed and the project hasn't run init yet, print a one-line next-step
+ * so agents/humans discover it (this is the most common fresh-install entry).
+ *
+ * Self-contained: core is a separate package and cannot import the CLI, so the
+ * agent-doc locations + marker below intentionally DUPLICATE the CLI's agent-doc
+ * discovery in packages/cli/src/commands/agent-docs.mjs — keep them aligned with
+ * that file. The .hermes.md / HERMES.md entries are an intentional superset (the
+ * CLI writes those via `--agent hermes`). Non-interactive, never fails the
+ * install, and quiet in the monorepo build, during npx's fetch, and once set up.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const HERE = fileURLToPath(import.meta.url);
+
+// Duplicates the CLI's agent-doc locations + markers — keep aligned with
+// packages/cli/src/commands/agent-docs.mjs. Hermes files are an intentional superset.
+const AGENT_DOC_PATHS = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.claude/CLAUDE.md',
+  '.cursorrules',
+  '.hermes.md',
+  'HERMES.md',
+];
+const MARKERS = ['<!-- ASTRYX:START -->', '<!-- XDS:START -->'];
+
+/**
+ * True when the project already has the Astryx agent prompt installed (an Astryx
+ * marker is present in any agent-doc file) — the same check the CLI performs.
+ * @param {string} root @returns {boolean}
+ */
+export function isAstryxInitialized(root) {
+  for (const rel of AGENT_DOC_PATHS) {
+    try {
+      const content = fs.readFileSync(path.join(root, rel), 'utf-8');
+      if (MARKERS.some(m => content.includes(m))) return true;
+    } catch {
+      // Unreadable/missing — keep checking the others.
+    }
+  }
+  return false;
+}
+
+/**
+ * Pure decision: should the postinstall print the setup nudge? Unit-testable
+ * without an actual npm install.
+ * @returns {boolean}
+ */
+export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
+  if (!scriptPath || !scriptPath.includes('node_modules')) return false; // monorepo/source build
+  if (scriptPath.includes('_npx') || npmCommand === 'exec') return false; // npx transient
+  if (isSetUp) return false; // already set up — stay quiet
+  return true;
+}
+
+function main() {
+  const root = process.env.INIT_CWD || process.cwd();
+  if (
+    shouldNudge({
+      scriptPath: HERE,
+      npmCommand: process.env.npm_command,
+      isSetUp: isAstryxInitialized(root),
+    })
+  ) {
+    // Scoped package form (`@astryxdesign/cli`) — always resolves to us, even
+    // before the CLI is installed. Bare `npx astryx` would fetch an unrelated
+    // look-alike package (see PR #4151). After that lands, switch this to its
+    // getCliInvocation() single source of truth.
+    process.stdout.write(
+      '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n',
+    );
+  }
+}
+
+// Run only when executed directly (`node scripts/postinstall.mjs`), never when
+// imported by tests.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  try {
+    main();
+  } catch {
+    // never break an install
+  }
+  process.exit(0);
+}

package/src/Avatar/Avatar.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       'Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.',
     bestPractices: [
       {guidance: true, description: 'Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.'},
-      {guidance: true, description: 'Pick a size that matches the context: tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers.'},
+      {guidance: true, description: 'Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.'},
       {guidance: true, description: 'Add a status dot when knowing someone\'s availability matters, like in chat or team views.'},
       {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular to stay consistent across the system.'},
@@ -55,9 +55,9 @@ export const docs = {
     },
     {
       name: 'size',
-      type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number",
-      description: "Avatar size. Use a named size ('tiny', 'xsmall', 'small', 'medium', 'large') or a numeric pixel value. Note: short names like 'sm', 'md', 'lg' are NOT valid; use the full words.",
-      default: "'small'",
+      type: "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | number",
+      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs.",
+      default: "'md'",
     },
     {
       name: 'status',
@@ -100,7 +100,7 @@ export const docsDense = {
       'Avatar represents a person or team with a profile photo, initials, or a default icon. Falls back automatically. Use in comment headers, contact lists, chat, user cards.',
     bestPractices: [
       {guidance: true, description: 'Always pass a name for initials fallback and screen reader alt text.'},
-      {guidance: true, description: 'Match size to context: tiny/xsmall inline, small/medium in lists, large for profiles.'},
+      {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
       {guidance: false, description: 'Use for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
@@ -111,7 +111,7 @@ export const docsDense = {
     fallbackSrc: 'fallback image when primary fails',
     name: 'user name for initials and alt text',
     alt: 'alt text; falls back to name',
-    size: "avatar size. Named ('tiny', 'xsmall', 'small', 'medium', 'large') or numeric px. Short names 'sm'/'md'/'lg' are NOT valid; use full words.",
+    size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
     status: 'corner content for status indicators',
   },
   components: [

package/src/Avatar/Avatar.tsx

@@ -55,9 +55,13 @@ const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 const INITIALS_FONT_SIZE_RATIO = 0.4;
 
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
-type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
+type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 
 /**
  * Numeric size options (in pixels)
@@ -78,15 +82,15 @@ export function resolveSize(size: AvatarSize): number {
     return size;
   }
   switch (size) {
-    case 'tiny':
+    case 'xsm':
       return 20;
-    case 'xsmall':
+    case 'sm':
       return 24;
-    case 'small':
+    case 'md':
       return 36;
-    case 'medium':
+    case 'lg':
       return 48;
-    case 'large':
+    case 'xl':
       return 128;
   }
 }
@@ -198,8 +202,9 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    */
   name?: string;
   /**
-   * The size of the avatar.
-   * @default 'small'
+   * The size of the avatar. A named size (`xsm` 20px, `sm` 24px, `md` 36px,
+   * `lg` 48px, `xl` 128px) or a specific pixel value.
+   * @default 'md'
    */
   size?: AvatarSize;
   /**
@@ -258,7 +263,7 @@ function DefaultIcon({size}: {size: number}) {
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */
@@ -267,7 +272,7 @@ export function Avatar({
   'data-testid': testId,
   fallbackSrc,
   name,
-  size = 'small',
+  size = 'md',
   src,
   status,
   xstyle,

package/src/Avatar/AvatarSizeContext.ts

@@ -18,7 +18,7 @@ import {createContext} from 'react';
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export const AvatarSizeContext = createContext<number>(36);
 AvatarSizeContext.displayName = 'AvatarSizeContext';

package/src/Avatar/AvatarStatusDot.tsx

@@ -168,12 +168,12 @@ const variantStyleMap: Partial<
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -47,7 +47,7 @@ export const docs = {
       name: 'size',
       type: 'AvatarSize',
       description: 'Size applied to all avatars via context.',
-      default: "'small'",
+      default: "'md'",
     },
     {
       name: 'ref',

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -56,14 +56,14 @@ describe('AvatarGroup', () => {
 
   it('applies size class to the group', () => {
     render(
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         <Avatar name="Alice" />
       </AvatarGroup>,
     );
 
     const group = screen.getByRole('group');
     expect(group.className).toContain('astryx-avatar-group');
-    expect(group.className).toContain('medium');
+    expect(group.className).toContain('lg');
   });
 
   it('renders empty group when no children', () => {
@@ -134,7 +134,7 @@ describe('AvatarGroupOverflow', () => {
     const visibleCount = 3;
 
     render(
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {users.slice(0, visibleCount).map(name => (
           <Avatar key={name} name={name} />
         ))}
@@ -211,4 +211,18 @@ describe('AvatarGroupOverflow — hardening', () => {
 
     expect(screen.getByText('+999')).toBeInTheDocument();
   });
+
+  it('renders the full "+N" text for wide multi-digit counts', () => {
+    // The indicator grows into a pill for long counts, so the entire number
+    // must remain present (nothing clipped away in the DOM).
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={4912} />
+      </AvatarGroup>,
+    );
+
+    expect(screen.getByText('+4912')).toBeInTheDocument();
+    expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+  });
 });

package/src/AvatarGroup/AvatarGroup.tsx

@@ -39,7 +39,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
   children: ReactNode;
   /**
    * Size applied to all avatars via context.
-   * @default 'small'
+   * @default 'md'
    */
   size?: AvatarSize;
   /**
@@ -65,7 +65,7 @@ const styles = stylex.create({
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}
@@ -75,7 +75,7 @@ const styles = stylex.create({
  */
 export function AvatarGroup({
   children,
-  size = 'small',
+  size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   xstyle,

package/src/AvatarGroup/AvatarGroupOverflow.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       'AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.',
     bestPractices: [
       {guidance: true, description: 'Pass the real hidden count to `count` so the accessible label matches the visible indicator.'},
-      {guidance: true, description: 'Use short custom text such as `+12` or `99+`; the indicator is sized like an avatar.'},
+      {guidance: true, description: 'Use short custom text such as `+12` or `99+`. The indicator is circular for short counts and grows into a pill for wider counts so the number always fits.'},
       {guidance: true, description: 'Provide `onClick` when the overflow opens a member list, popover, or detail view.'},
       {guidance: false, description: 'Do not use long labels inside the indicator; place longer participant details next to the group instead.'},
     ],
@@ -64,7 +64,7 @@ export const docs = {
     {
       label: 'Default overflow count',
       code: `
-<AvatarGroup size="medium">
+<AvatarGroup size="lg">
   {users.slice(0, 3).map(user => (
     <Avatar key={user.id} src={user.src} name={user.name} />
   ))}
@@ -75,7 +75,7 @@ export const docs = {
     {
       label: 'Custom count text',
       code: `
-<AvatarGroup size="medium">
+<AvatarGroup size="lg">
   {users.slice(0, 3).map(user => (
     <Avatar key={user.id} src={user.src} name={user.name} />
   ))}
@@ -104,7 +104,7 @@ export const docsZh = {
       'AvatarGroupOverflow 显示在 AvatarGroup 末尾，用来汇总未单独展示的成员。适用于只展示少量头像但仍需要显示隐藏数量的场景。',
     bestPractices: [
       {guidance: true, description: '向 `count` 传入真实隐藏数量，确保无障碍标签与可见指示器一致。'},
-      {guidance: true, description: '使用 `+12` 或 `99+` 等短文本；指示器尺寸与头像相同。'},
+      {guidance: true, description: '使用 `+12` 或 `99+` 等短文本；指示器在计数较短时为圆形，计数较宽时会拉伸为胶囊形，确保数字始终完整显示。'},
       {guidance: true, description: '当溢出项会打开成员列表、弹出层或详情视图时提供 `onClick`。'},
       {guidance: false, description: '不要在指示器内使用长标签；更长的参与者详情应放在头像组旁边。'},
     ],

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -20,6 +20,7 @@ import {
   typographyVars,
   fontWeightVars,
   radiusVars,
+  spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {useAvatarGroup} from './AvatarGroupContext';
@@ -67,13 +68,21 @@ const styles = stylex.create({
     borderWidth: BORDER_WIDTH,
     borderStyle: 'solid',
     borderColor: colorVars['--color-background-surface'],
-    boxSizing: 'content-box',
+    // border-box so the border and inline padding are included in the box
+    // size: a short "+N" stays a circle at exactly the avatar size, while
+    // longer content pushes past the min width and grows into a pill.
+    boxSizing: 'border-box',
+    // Horizontal breathing room so multi-digit "+N" counts don't crowd the
+    // edges once the indicator grows into a pill.
+    paddingInline: spacingVars['--spacing-2'],
     // Neutral tint layer (preserves opaque base underneath)
     backgroundImage: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
   },
   button: {
     cursor: 'pointer',
-    padding: 0,
+    // Reset the UA button's block padding only; the inline padding from `base`
+    // provides the pill's breathing room and must be preserved.
+    paddingBlock: 0,
     // Interactive overlay states layered on top via backgroundImage
     backgroundImage: {
       default: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
@@ -99,8 +108,15 @@ const styles = stylex.create({
 
 const dynamicStyles = stylex.create({
   size: (s: number) => ({
-    width: s,
-    height: s,
+    // Pin height to the avatar's rendered size and enforce the same value as a
+    // *minimum* width, so short counts (`+5`) render a perfect circle. With
+    // border-box, the inline padding lives inside this size; longer content
+    // (`+4912`) pushes past the min width and grows into a stadium/pill.
+    // The border is added to the declared size (like the avatars' ring, which
+    // uses content-box + a 2px border) to keep the indicator the same overall
+    // size as its sibling avatars.
+    minWidth: s + BORDER_WIDTH * 2,
+    height: s + BORDER_WIDTH * 2,
   }),
   fontSize: (s: number) => ({
     fontSize: s * OVERFLOW_FONT_RATIO,
@@ -116,7 +132,7 @@ const dynamicStyles = stylex.create({
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/src/Carousel/Carousel.doc.mjs

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

@@ -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)
@@ -111,4 +111,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,9 @@
  * @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.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)
@@ -290,6 +291,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 +372,7 @@ export function Carousel({
       <div
         ref={composedRef}
         tabIndex={0}
+        onWheel={handleWheel}
         {...stylex.props(
           styles.scroller,
           gapStyles[gap],

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.' },