@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

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';
@@ -89,6 +97,11 @@ type AvatarNumericSize =
  */
 export type AvatarSize = AvatarNamedSize | AvatarNumericSize;
 
+/**
+ * Avatar shape options
+ */
+export type AvatarShape = 'circle' | 'rounded' | 'square';
+
 /**
  * Resolves named sizes to their numeric pixel values
  */
@@ -110,6 +123,25 @@ export function resolveSize(size: AvatarSize): number {
   }
 }
 
+// Sets one local custom property rather than `borderRadius` directly, so
+// every clipping/ring surface that needs the shape's radius (the wrapper,
+// the interactive focus ring, the content div that actually clips via
+// `overflow: hidden`, and AvatarGroupOverflow's "+N" indicator) reads the
+// same value instead of each hardcoding its own borderRadius independently.
+// A theme override only has to reach this one property, not fight the
+// per-surface StyleX class order to change the shape everywhere at once.
+export const shapeStyles = stylex.create({
+  circle: {
+    '--_avatar-radius': radiusVars['--radius-full'],
+  },
+  rounded: {
+    '--_avatar-radius': radiusVars['--radius-element'],
+  },
+  square: {
+    '--_avatar-radius': radiusVars['--radius-none'],
+  },
+});
+
 /**
  * Base styles for the avatar
  * Uses a wrapper/content structure so status isn't clipped by overflow:hidden
@@ -119,10 +151,10 @@ const styles = stylex.create({
     position: 'relative',
     display: 'inline-flex',
     flexShrink: 0,
-    // The wrapper carries the avatar's box as well as its radius, so a theme
-    // rule on the `.astryx-avatar` target reaches both: the size the `size`
-    // visual prop selects on is set here, and the content below fills it.
-    borderRadius: radiusVars['--radius-full'],
+    // Reads the shape variant's `--_avatar-radius` (set by `shapeStyles`
+    // below) rather than a hardcoded value, so `shape` actually changes the
+    // wrapper's own radius instead of only the content div's clip.
+    borderRadius: 'var(--_avatar-radius)',
   },
   content: {
     display: 'flex',
@@ -130,9 +162,14 @@ const styles = stylex.create({
     justifyContent: 'center',
     width: '100%',
     height: '100%',
-    borderRadius: radiusVars['--radius-full'],
     overflow: 'hidden',
     userSelect: 'none',
+    // The content div is the one that actually clips (via overflow: hidden
+    // above), so it needs its own border-radius matching the wrapper's.
+    // It inherits `--_avatar-radius` from the wrapper, since custom
+    // properties cascade to descendants even though border-radius itself
+    // does not.
+    borderRadius: 'var(--_avatar-radius)',
   },
   image: {
     width: '100%',
@@ -159,9 +196,6 @@ const styles = stylex.create({
   status: {
     position: 'absolute',
   },
-  // Visible focus ring for the name-tooltip tab stop, matching the repo-wide
-  // focus-visible outline treatment (see Timestamp, Token, Thumbnail). Only
-  // applied when a tooltip is active so keyboard users can reveal it.
   // Reset the intrinsic styling of the interactive element (<a>/<button>) so it
   // is a transparent, correctly-sized wrapper around the avatar visuals. The
   // element carries the focus-visible accent ring for keyboard users.
@@ -179,8 +213,9 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    // Match the avatar's circular shape so the focus ring hugs it.
-    borderRadius: radiusVars['--radius-full'],
+    // Match the avatar's shape (via `--_avatar-radius`) so the focus ring
+    // hugs it, whichever shape variant is in effect.
+    borderRadius: 'var(--_avatar-radius)',
   },
 });
 
@@ -199,7 +234,7 @@ const dynamicStyles = stylex.create({
   fontSize: (size: number) => ({
     fontSize: `${size * INITIALS_FONT_SIZE_RATIO}px`,
   }),
-  statusPosition: (size: number) => ({
+  statusPositionCircle: (size: number) => ({
     bottom: size * CIRCLE_EDGE_OFFSET_RATIO,
     insetInlineEnd: size * CIRCLE_EDGE_OFFSET_RATIO,
     // `insetInlineEnd` anchors to the right edge in LTR / left in RTL, so the
@@ -209,13 +244,23 @@ const dynamicStyles = stylex.create({
       ':is([dir="rtl"] *)': 'translate(-50%, 50%)',
     },
   }),
+  statusPositionCorner: {
+    bottom: 0,
+    insetInlineEnd: 0,
+    // Same RTL mirroring as statusPositionCircle above: insetInlineEnd
+    // anchors to the right edge in LTR / left in RTL, so the outward push
+    // must flip sign too.
+    transform: {
+      default: 'translate(25%, 25%)',
+      ':is([dir="rtl"] *)': 'translate(-25%, 25%)',
+    },
+  },
 });
 
 const BORDER_WIDTH = 2;
 
 const groupStyles = stylex.create({
   ring: {
-    borderRadius: radiusVars['--radius-full'],
     borderWidth: BORDER_WIDTH,
     borderStyle: 'solid',
     borderColor: colorVars['--color-background-surface'],
@@ -268,6 +313,14 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    * @default 'md'
    */
   size?: AvatarSize;
+  /**
+   * Shape variant of the avatar.
+   * - 'circle': Full circle (default)
+   * - 'rounded': Rounded square
+   * - 'square': Sharp square
+   * @default 'circle'
+   */
+  shape?: AvatarShape;
   /**
    * The primary image source for the avatar.
    */
@@ -471,6 +524,7 @@ export function Avatar({
   fallbackSrc,
   name,
   size = 'md',
+  shape = 'circle',
   src,
   status,
   tooltip = true,
@@ -530,6 +584,7 @@ export function Avatar({
     : undefined;
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
+  const resolvedShape = avatarGroup?.shape ?? shape;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
 
   // Resolve the tooltip content:
@@ -608,47 +663,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,
@@ -700,7 +770,9 @@ export function Avatar({
         <div
           {...stylex.props(
             styles.status,
-            dynamicStyles.statusPosition(numericSize),
+            resolvedShape === 'circle'
+              ? dynamicStyles.statusPositionCircle(numericSize)
+              : dynamicStyles.statusPositionCorner,
           )}>
           {status}
         </div>
@@ -713,7 +785,7 @@ export function Avatar({
   // tooltip tab-stop focus ring all live here so the interactive
   // `<a>`/`<button>` and the static `<div>` carry the exact same box.
   const rootStylexProps = mergeProps(
-    themeProps('avatar', {size: resolvedSize}),
+    themeProps('avatar', {size: resolvedSize, shape: resolvedShape}),
     focusOutlineProps.focusVisible(
       styles.wrapper,
       dynamicStyles.size(numericSize),
@@ -721,6 +793,7 @@ export function Avatar({
       avatarGroup && groupStyles.ring,
       avatarGroup && groupStyles.overlap,
       avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),
+      shapeStyles[resolvedShape],
       xstyle,
     ),
     className,

package/src/Avatar/index.ts

@@ -5,7 +5,7 @@
 /**
  * @file index.ts
  * @input Imports Avatar component and types from Avatar.tsx, AvatarStatusDot from AvatarStatusDot.tsx
- * @output Exports Avatar, AvatarProps, AvatarSize, AvatarStatusDot, AvatarStatusDotProps, AvatarStatusDotVariant
+ * @output Exports Avatar, AvatarProps, AvatarSize, AvatarShape, resolveSize, AvatarStatusDot, AvatarStatusDotProps, AvatarStatusDotVariant
  * @position Component entry point; re-exported by /packages/core/src/index.ts
  *
  * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs
@@ -38,7 +38,7 @@ export interface AvatarStatusDotVariantMap {
 }
 
 export {Avatar, resolveSize} from './Avatar';
-export type {AvatarProps, AvatarSize} from './Avatar';
+export type {AvatarProps, AvatarSize, AvatarShape} from './Avatar';
 export {AvatarStatusDot} from './AvatarStatusDot';
 export type {
   AvatarStatusDotProps,

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -25,8 +25,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-avatar-group', visualProps: ['size']},
-      {className: 'astryx-avatar-group-overflow', visualProps: ['size']},
+      {className: 'astryx-avatar-group', visualProps: ['size', 'shape']},
+      {className: 'astryx-avatar-group-overflow', visualProps: ['size', 'shape']},
     ],
   },
   description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.',
@@ -52,6 +52,12 @@ export const docs = {
         "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
       default: "'md'",
     },
+    {
+      name: 'shape',
+      type: "'circle' | 'rounded' | 'square'",
+      description: "Shape applied to all avatars via context, overriding each avatar's own shape prop. Also applied to AvatarGroupOverflow's \"+N\" indicator.",
+      default: "'circle'",
+    },
     {
       name: 'ref',
       type: 'React.Ref<HTMLDivElement>',

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -118,6 +118,30 @@ describe('AvatarGroupOverflow', () => {
     expect(overflow).toHaveAttribute('data-size', 'lg');
   });
 
+  it('applies the group shape to the overflow chip, matching its avatars', () => {
+    render(
+      <AvatarGroup shape="square">
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByLabelText('5 more');
+    expect(overflow).toHaveAttribute('data-shape', 'square');
+  });
+
+  it('defaults the overflow chip to circle shape with no explicit AvatarGroup shape', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByLabelText('5 more');
+    expect(overflow).toHaveAttribute('data-shape', 'circle');
+  });
+
   it('renders as button when onClick is provided', () => {
     render(
       <AvatarGroup>

package/src/AvatarGroup/AvatarGroup.tsx

@@ -26,9 +26,9 @@
 
 import {useId, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
-import {resolveSize, type AvatarSize} from '../Avatar';
+import {resolveSize, type AvatarShape, 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> {
@@ -54,6 +55,13 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
    * @default 'md'
    */
   size?: AvatarSize;
+  /**
+   * Shape applied to all avatars via context, overriding each avatar's own
+   * `shape` prop so a group stays visually uniform. Also applied to the
+   * `AvatarGroupOverflow` "+N" indicator, so it matches the group.
+   * @default 'circle'
+   */
+  shape?: AvatarShape;
   /**
    * Test ID for integration testing.
    */
@@ -88,6 +96,7 @@ const styles = stylex.create({
 export function AvatarGroup({
   children,
   size = 'md',
+  shape = 'circle',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   'aria-describedby': ariaDescribedByFromProps,
@@ -105,8 +114,8 @@ export function AvatarGroup({
   const overlap = Math.round(numericSize * OVERLAP_RATIO);
 
   const contextValue = useMemo(
-    () => ({size, overlap, numericSize}),
-    [size, overlap, numericSize],
+    () => ({size, shape, overlap, numericSize}),
+    [size, shape, overlap, numericSize],
   );
 
   // The keyboard hint and roving tab stop only make sense once the group has
@@ -143,7 +152,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}
@@ -151,7 +160,7 @@ export function AvatarGroup({
         onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
         onFocus={composeEventHandlers(onFocus, handleFocus)}
         {...mergeProps(
-          themeProps('avatar-group', {size}),
+          themeProps('avatar-group', {size, shape}),
           stylex.props(styles.root, xstyle),
           className,
           style,

package/src/AvatarGroup/AvatarGroupContext.ts

@@ -9,16 +9,18 @@
  */
 
 import {createContext, use} from 'react';
-import type {AvatarSize} from '../Avatar';
+import type {AvatarShape, AvatarSize} from '../Avatar';
 
 export interface AvatarGroupContextValue {
   size: AvatarSize;
+  shape: AvatarShape;
   overlap: number;
   numericSize: number;
 }
 
-export const AvatarGroupContext =
-  createContext<AvatarGroupContextValue | null>(null);
+export const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(
+  null,
+);
 AvatarGroupContext.displayName = 'AvatarGroupContext';
 
 export function useAvatarGroup(): AvatarGroupContextValue | null {

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -20,9 +20,9 @@ import {
   typographyVars,
   typeScaleVars,
   fontWeightVars,
-  radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
+import {shapeStyles} from '../Avatar/Avatar';
 import {mergeProps} from '../utils';
 import {resolveSize} from '../Avatar';
 import {useAvatarGroup} from './AvatarGroupContext';
@@ -65,7 +65,10 @@ const styles = stylex.create({
     display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
-    borderRadius: radiusVars['--radius-full'],
+    // Reads the shape variant's `--_avatar-radius` (set via `shapeStyles`,
+    // shared with Avatar) so the overflow indicator matches the group's
+    // shape instead of always staying a circle.
+    borderRadius: 'var(--_avatar-radius)',
     // Use opaque background to prevent avatar bleed-through
     backgroundColor: colorVars['--color-background-surface'],
     color: colorVars['--color-text-secondary'],
@@ -166,6 +169,7 @@ export function AvatarGroupOverflow({
   const t = useTranslator();
   const group = useAvatarGroup();
   const size = group?.size ?? 'md';
+  const shape = group?.shape ?? 'circle';
   const numericSize = group?.numericSize ?? resolveSize('md');
   const overlap = group?.overlap ?? 0;
 
@@ -186,7 +190,7 @@ export function AvatarGroupOverflow({
         aria-label={label}
         data-avatar-item=""
         {...mergeProps(
-          themeProps('avatar-group-overflow', {size}),
+          themeProps('avatar-group-overflow', {size, shape}),
           focusOutlineProps.focusVisible(
             styles.base,
             styles.button,
@@ -194,6 +198,7 @@ export function AvatarGroupOverflow({
             dynamicStyles.size(numericSize),
             dynamicStyles.fontSize(numericSize),
             dynamicStyles.overlap(-overlap),
+            shapeStyles[shape],
             xstyle,
           ),
           className,
@@ -210,13 +215,14 @@ export function AvatarGroupOverflow({
       {...rest}
       aria-label={label}
       {...mergeProps(
-        themeProps('avatar-group-overflow', {size}),
+        themeProps('avatar-group-overflow', {size, shape}),
         stylex.props(
           styles.base,
           styles.overlap,
           dynamicStyles.size(numericSize),
           dynamicStyles.fontSize(numericSize),
           dynamicStyles.overlap(-overlap),
+          shapeStyles[shape],
           xstyle,
         ),
         className,

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()',
   },
 };