@astryxdesign/core 0.4.7 → 0.5.0-canary.07f6c33

package/locales/pseudo.json

@@ -422,6 +422,9 @@
   "@astryx.table.filter.apply": {
     "defaultMessage": "⟦Àþþłý⟧"
   },
+  "@astryx.table.rowStatus.columnHeader": {
+    "defaultMessage": "⟦Řóŵ šţàţúš⟧"
+  },
   "@astryx.table.selection.selectAllRows": {
     "defaultMessage": "⟦Šéłéçţ àłł řóŵš⟧"
   },
@@ -560,6 +563,9 @@
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "⟦{label} ţíɱé⟧"
   },
+  "@astryx.dateTimeInput.timeOptionsLabel": {
+    "defaultMessage": "⟦{label} óþţíóñš⟧"
+  },
   "@astryx.dateRangeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ ðàţé řàñĝé⟧"
   },
@@ -608,6 +614,12 @@
   "@astryx.table.pagination.label": {
     "defaultMessage": "⟦Ţàƀłé þàĝíñàţíóñ⟧"
   },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "⟦{label} (ţóþ)⟧"
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "⟦{label} (ƀóţţóɱ)⟧"
+  },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ à ţíɱé⟧"
   },
@@ -794,12 +806,18 @@
   "@astryx.tableRowExpansion.expandRow": {
     "defaultMessage": "⟦Éẋþàñð řóŵ⟧"
   },
+  "@astryx.tableRowExpansion.columnHeader": {
+    "defaultMessage": "⟦Řóŵ éẋþàñšíóñ⟧"
+  },
   "@astryx.tableRowExpansion.collapseAllRows": {
     "defaultMessage": "⟦Çółłàþšé àłł řóŵš⟧"
   },
   "@astryx.tableRowExpansion.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.stepper.label": {
+    "defaultMessage": "⟦Þřóĝřéšš⟧"
+  },
   "@astryx.step.goToStep": {
     "defaultMessage": "⟦Ĝó ţó šţéþ {stepNumber, number}: {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.7",
+  "version": "0.5.0-canary.07f6c33",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -489,6 +489,11 @@
       "types": "./dist/StatusDot/index.d.ts",
       "default": "./dist/StatusDot/index.js"
     },
+    "./Stepper": {
+      "source": "./src/Stepper/index.ts",
+      "types": "./dist/Stepper/index.d.ts",
+      "default": "./dist/Stepper/index.js"
+    },
     "./Switch": {
       "source": "./src/Switch/index.ts",
       "types": "./dist/Switch/index.d.ts",
@@ -656,6 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.5.0-canary.07f6c33",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -664,8 +670,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.7"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/AppShell.tsx

@@ -50,7 +50,7 @@ import {AppShellMobileContext} from './AppShellMobileContext';
 import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {mergeProps, isRenderable} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
@@ -58,6 +58,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {AppShellVariantMap} from './index';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
   ? ({
@@ -792,7 +793,7 @@ export function AppShell({
     <AppShellMobileContext value={mobileContextValue}>
       <div
         {...rest}
-        ref={mergeRefs(ref, shellRef)}
+        ref={useMergedRefs(ref, shellRef)}
         data-testid={dataTestId}
         {...mergeProps(
           themeProps('app-shell', {variant}),

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -30,7 +31,7 @@ export const docs = {
     {
       name: 'ratio',
       type: 'number',
-      description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+      description: 'Aspect ratio as width/height (e.g. 16/9, 1). Emitted as a class-level declaration (never inline), so `xstyle` rules or unlayered consumer CSS can override it responsively.',
       required: true,
     },
     {
@@ -83,6 +84,7 @@ export const docsZh = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -94,7 +96,7 @@ export const docsZh = {
     ],
   },
   props: [
-    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。以类级声明输出（非内联样式），可通过 `xstyle` 规则或未分层的（unlayered）消费者 CSS 做响应式覆盖。', required: true},
     {
       name: 'shape',
       type: "'rectangle' | 'ellipse'",
@@ -133,6 +135,7 @@ export const docsDense = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -144,7 +147,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    ratio: 'width/height ratio (e.g. 16/9, 1)',
+    ratio: 'width/height ratio (e.g. 16/9, 1); class-level declaration (never inline) so xstyle/unlayered-CSS @container overrides win',
     shape: "container shape: 'rectangle' (default) | 'ellipse' (circle at ratio 1)",
     fit: "child layout: 'cover' fill+crop | 'contain' fill+letterbox | 'center' natural size; omitted = child styles itself",
     children: 'content positioned absolutely to fill container',

package/src/AspectRatio/AspectRatio.test.tsx

@@ -13,6 +13,20 @@ import {describe, it, expect, vi, beforeAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
+/**
+ * The ratio compiles to a class-level `aspect-ratio: var(--x-aspectRatio)`
+ * declaration with the value carried by a CSS variable (so xstyle/@media
+ * and unlayered consumer CSS overrides can win). `--x-aspectRatio` is the
+ * debug-mode variable name emitted for the `aspectRatio` property.
+ */
+function ratioVar(el: HTMLElement): string {
+  return el.style.getPropertyValue('--x-aspectRatio');
+}
+
+function ratioValue(ratio: number): string {
+  return String(ratio);
+}
+
 describe('AspectRatio', () => {
   it('renders with correct aspect ratio', () => {
     render(
@@ -22,7 +36,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     expect(element).toBeInTheDocument();
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
   });
 
   it('children fill the container', () => {
@@ -47,7 +61,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 4:3 ratio', () => {
@@ -58,7 +72,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 1:1 square ratio', () => {
@@ -68,7 +82,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
   });
 
   it('renders with 21:9 ultrawide ratio', () => {
@@ -79,7 +93,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
@@ -89,7 +103,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('ellipse');
   });
 
@@ -101,7 +115,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     // Ratio is preserved — the ellipse does not force 1:1.
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     expect(element.className).toContain('ellipse');
   });
 
@@ -112,7 +126,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('rectangle');
     // No ellipse border-radius when shape is the default rectangle
     expect(element.style.borderRadius).toBe('');
@@ -177,6 +191,38 @@ describe('AspectRatio', () => {
     expect(video).toBeInTheDocument();
   });
 
+  describe('responsive ratio', () => {
+    it('emits the ratio as a class-level declaration, not an inline style', () => {
+      render(
+        <AspectRatio ratio={3 / 1} data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // No inline aspect-ratio — the declaration lives in a class reading a
+      // CSS variable, so @media/@container rules (via xstyle, or via
+      // unlayered consumer CSS beating the astryx-base layer) can override
+      // it.
+      expect(element.style.aspectRatio).toBe('');
+      expect(ratioVar(element)).toBe(ratioValue(3 / 1));
+    });
+
+    it('lets a consumer inline style win over the class-level ratio', () => {
+      render(
+        <AspectRatio
+          ratio={3 / 1}
+          style={{aspectRatio: '3 / 2'}}
+          data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // The consumer's style prop passes through untouched (it is no longer
+      // merged with a component-owned inline aspect-ratio).
+      expect(element.style.aspectRatio).toBe('3 / 2');
+    });
+  });
+
   describe('fit', () => {
     it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="cover"', () => {
       render(
@@ -277,7 +323,7 @@ describe('AspectRatio', () => {
   });
 
   describe('style merging', () => {
-    it('keeps the consumer style and applies the ratio over it', () => {
+    it('keeps the consumer style and lets an inline ratio win', () => {
       render(
         <AspectRatio
           ratio={16 / 9}
@@ -288,7 +334,8 @@ describe('AspectRatio', () => {
       );
       const element = screen.getByTestId('aspect-ratio');
       expect(element.style.opacity).toBe('0.5');
-      expect(element.style.aspectRatio).toBe(String(16 / 9));
+      expect(element.style.aspectRatio).toBe('3 / 1');
+      expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     });
 
     it('keeps a consumer className beside the theme target', () => {

package/src/AspectRatio/AspectRatio.tsx

@@ -43,6 +43,25 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+   *
+   * The ratio is emitted as a class-level declaration — never an inline
+   * style — so it can be made responsive:
+   * - StyleX consumers pass an `aspect-ratio` rule via `xstyle`, including
+   *   under `@media`/`@container` conditions.
+   * - Plain-CSS/Tailwind consumers override `aspect-ratio` from their own
+   *   (unlayered) rules: the compiled component styles live in the
+   *   `astryx-base` cascade layer, and unlayered CSS wins over layered
+   *   rules regardless of specificity.
+   *
+   * @example
+   * ```
+   * // 3:1 hero that becomes 3:2 when its container stacks
+   * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
+   *
+   * // CSS: @container gallery (max-width: 720px) {
+   * //   .gallery-hero { aspect-ratio: 3 / 2; }
+   * // }
+   * ```
    */
   ratio: number;
 
@@ -132,6 +151,20 @@ const styles = stylex.create({
   },
 });
 
+// The ratio compiles to a CSS variable + a class-level declaration
+// (aspect-ratio: var(--x)) instead of a raw inline style, so consumer
+// overrides — `xstyle` rules, including ones inside @media/@container
+// queries — can still win. A raw inline `aspect-ratio` would beat any class
+// (same rationale as Grid's dynamic track values). Non-StyleX consumers
+// don't need a dedicated hook: the compiled declaration sits in the
+// `astryx-base` cascade layer, so any unlayered consumer rule wins
+// regardless of specificity.
+const dynamicStyles = stylex.create({
+  ratio: (ratio: number) => ({
+    aspectRatio: ratio,
+  }),
+});
+
 /**
  * AspectRatio component for maintaining a specific aspect ratio for its children.
  *
@@ -147,6 +180,11 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or
@@ -188,11 +226,12 @@ export function AspectRatio({
         themeProps('aspect-ratio', {shape}),
         stylex.props(
           styles.container,
+          dynamicStyles.ratio(ratio),
           shape === 'ellipse' && styles.ellipse,
           xstyle,
         ),
         className,
-        {...style, aspectRatio: ratio},
+        style,
       )}
       {...props}>
       {/* The marker attribute carries the fit value so the reset.css child

package/src/Avatar/Avatar.doc.mjs

@@ -148,7 +148,8 @@ export const docsDense = {
       {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: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
-      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development. A status label is not a name.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development.'},
+      {guidance: false, description: 'Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.'},
       {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.'},
     ],

package/src/Avatar/Avatar.test.tsx

@@ -569,6 +569,23 @@ describe('Avatar', () => {
       render(<Avatar name="Ada Lovelace" ref={ref} data-testid="a" />);
       expect(ref.current).toBe(screen.getByTestId('a'));
     });
+
+    it('keeps its merged ref attached across unrelated rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Avatar name="Ada Lovelace" size="sm" tooltip={false} ref={ref} />,
+      );
+      const avatar = screen.getByRole('img', {name: 'Ada Lovelace'});
+      expect(ref).toHaveBeenLastCalledWith(avatar);
+      ref.mockClear();
+
+      rerender(
+        <Avatar name="Ada Lovelace" size="lg" tooltip={false} ref={ref} />,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByRole('img', {name: 'Ada Lovelace'})).toBe(avatar);
+    });
   });
 });
 

package/src/Avatar/Avatar.tsx

@@ -19,7 +19,14 @@
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
 
-import {isValidElement, useMemo, useRef, useState, type ReactNode} from 'react';
+import {
+  isValidElement,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -34,7 +41,8 @@ import {
   type AvatarStatusLabelTarget,
 } from './AvatarStatusLabelContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {themeProps} from '../utils/themeProps';
 import {firstCharacter} from '../utils/characters';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -608,47 +616,62 @@ export function Avatar({
     label: undefined,
     update: null,
   });
-  // A fresh callback ref every render, so React reattaches it on every commit
-  // and the name is recomposed after React has written this render's props.
+  const {
+    'aria-hidden': consumerAriaHidden,
+    'aria-label': consumerAriaLabel,
+    role: consumerRole,
+  } = props;
+  // Recompose the name after React has written any relevant prop changes.
   // `update` covers the other direction: a label that changes while the avatar
   // itself does not re-render.
-  const nameRef = (element: HTMLElement | null) => {
-    if (element == null) {
-      return;
-    }
-    const target = statusLabelRef.current;
-    target.update = () => {
-      const composed = composeAccessibleName(
-        t,
-        nameLabel,
-        meaningful(target.label) ?? getStatusLabel(status),
-      );
-      // A consumer's own ARIA wins here exactly as it does in render, where
-      // the derived props spread before `{...props}`.
-      if (props['aria-label'] == null) {
-        setAttributeOrRemove(element, 'aria-label', composed);
+  const nameRef = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null) {
+        return;
       }
-      // An `<a>`/`<button>` root carries its own role and must not be hidden,
-      // so only the name transfers there.
-      if (!isInteractive) {
-        if (props.role == null) {
-          element.setAttribute('role', composed ? 'img' : 'presentation');
+      const target = statusLabelRef.current;
+      target.update = () => {
+        const composed = composeAccessibleName(
+          t,
+          nameLabel,
+          meaningful(target.label) ?? getStatusLabel(status),
+        );
+        // A consumer's own ARIA wins here exactly as it does in render, where
+        // the derived props spread before `{...props}`.
+        if (consumerAriaLabel == null) {
+          setAttributeOrRemove(element, 'aria-label', composed);
         }
-        if (props['aria-hidden'] == null) {
-          setAttributeOrRemove(
-            element,
-            'aria-hidden',
-            composed ? undefined : 'true',
-          );
+        // An `<a>`/`<button>` root carries its own role and must not be hidden,
+        // so only the name transfers there.
+        if (!isInteractive) {
+          if (consumerRole == null) {
+            element.setAttribute('role', composed ? 'img' : 'presentation');
+          }
+          if (consumerAriaHidden == null) {
+            setAttributeOrRemove(
+              element,
+              'aria-hidden',
+              composed ? undefined : 'true',
+            );
+          }
         }
-      }
-    };
-    target.update();
-    return () => {
-      target.update = null;
-    };
-  };
-  const rootRef = mergeRefs(
+      };
+      target.update();
+      return () => {
+        target.update = null;
+      };
+    },
+    [
+      consumerAriaHidden,
+      consumerAriaLabel,
+      consumerRole,
+      isInteractive,
+      nameLabel,
+      status,
+      t,
+    ],
+  );
+  const rootRef = useMergedRefs(
     ref,
     showTooltip ? tooltipHook.ref : undefined,
     nameRef,

package/src/AvatarGroup/AvatarGroup.tsx

@@ -28,7 +28,7 @@ import {useId, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import {resolveSize, type AvatarSize} from '../Avatar';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {AvatarGroupContext} from './AvatarGroupContext';
 import {themeProps} from '../utils/themeProps';
@@ -37,6 +37,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {VisuallyHidden} from '../VisuallyHidden';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const OVERLAP_RATIO = 0.25;
 
 export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
@@ -143,7 +144,7 @@ export function AvatarGroup({
     <AvatarGroupContext value={contextValue}>
       <div
         {...props}
-        ref={mergeRefs(ref, listRef)}
+        ref={useMergedRefs(ref, listRef)}
         role="group"
         aria-label={ariaLabel}
         aria-describedby={describedBy}

package/src/Banner/Banner.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
       {guidance: true, description: 'Keep titles short and scannable: "Payment failed" not "There was a problem processing your most recent payment."'},
       {guidance: false, description: 'Use Banner for short-lived messages that disappear on their own; use Toast instead.'},
       {guidance: false, description: 'Stack multiple banners with the same status; combine related messages into one banner.'},
+      {guidance: true, description: 'Set collapsible={false} when the user needs the content to act on the message, like the list of fields that failed validation. Keep the default toggle when the detail is long enough to bury the banner\u2019s own message.'},
       {guidance: true, description: 'Error and warning banners render as role="alert"; info and success render as role="status". Mount an alert banner in response to an event rather than on first paint, so assistive tech has a change to report.'},
       {guidance: false, description: 'Rely on the status color or icon alone to carry meaning; say which status it is in the title text, because the icon is decorative to a screen reader.'},
     ],
@@ -26,7 +27,7 @@ export const docs = {
       {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
+      {name: 'Content', required: false, description: 'Extra detail below the banner header, like a list of errors. Sits behind an expand/collapse toggle by default; set collapsible={false} to keep it visible.'},
     ],
   },
 
@@ -94,14 +95,14 @@ export const docs = {
       name: 'children',
       type: 'ReactNode',
       description:
-        'Content rendered in the card-background area below the colored header.',
+        'Content rendered in the card-background area below the colored header. Sits behind an expand/collapse toggle unless `collapsible={false}`.',
     },
     {
-      name: 'defaultIsExpanded',
-      type: 'boolean',
+      name: 'collapsible',
+      type: 'boolean | {defaultIsOpen?: boolean; isOpen?: boolean; onOpenChange?: (isOpen: boolean) => void}',
       description:
-        'Whether the content area (children) starts expanded. Only relevant when children are provided.',
-      default: 'false',
+        'Whether the content area (children) sits behind an expand/collapse toggle in the header. On by default, starting collapsed. `false` opts out: children are always visible with no toggle. `{defaultIsOpen: true}` starts open; `{isOpen, onOpenChange}` is controlled. Takes the same CollapsibleConfig as Collapsible.',
+      default: 'true',
     },
     {
       name: 'xstyle',
@@ -154,7 +155,7 @@ export const docsZh = {
       {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
+      {name: 'Content', required: false, description: 'Extra detail below the banner header, like a list of errors. Sits behind an expand/collapse toggle by default; set collapsible={false} to keep it visible.'},
     ],
   },
   props: [
@@ -167,8 +168,8 @@ export const docsZh = {
     {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。头部过窄时会整体换行到文本下方，自成一行。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
-    {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
-    {name: 'defaultIsExpanded', type: 'boolean', description: '内容区域（children）是否初始展开。仅在提供 children 时相关。', default: 'false'},
+    {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。默认位于展开/折叠开关之后，除非设置 collapsible={false}。'},
+    {name: 'collapsible', type: 'boolean | {defaultIsOpen?: boolean; isOpen?: boolean; onOpenChange?: (isOpen: boolean) => void}', description: '内容区域（children）是否位于头部的展开/折叠开关之后。默认开启，且初始为折叠状态。false 表示关闭：内容始终可见且没有开关。{defaultIsOpen: true} 表示初始展开；{isOpen, onOpenChange} 为受控模式。与 Collapsible 使用同一套 CollapsibleConfig。', default: 'true'},
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -230,7 +231,7 @@ export const docsDense = {
       {name: 'Description', required: false, description: 'Detail below title.'},
       {name: 'Action button', required: false, description: 'CTA like Review or Retry.'},
       {name: 'Dismiss button', required: false, description: 'Close button via isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Expandable detail area.'},
+      {name: 'Content', required: false, description: 'Detail area; behind a toggle unless collapsible={false}.'},
     ],
   },
   propDescriptions: {
@@ -243,7 +244,8 @@ export const docsDense = {
     endContent: 'end-aligned action in header, typically button/link; wraps to its own row when the header is too narrow',
     container: 'card=border-radius; section=full-width no radius for page-level',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
-    children: 'content in card-bg area below colored header',
+    children: 'content in card-bg area below colored header; behind a toggle unless collapsible={false}',
+    collapsible: 'children behind a header toggle; default true=collapsed. false=always visible, no toggle. {defaultIsOpen:true}=starts open, {isOpen,onOpenChange}=controlled',
     xstyle: 'StyleX layout customization via stylex.create()',
   },
 };