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

package/src/Banner/Banner.tsx

@@ -46,8 +46,10 @@ import {
   borderVars,
   durationVars,
   easeVars,
+  shadowVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import type {Elevation} from '../utils/types';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -157,6 +159,13 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
    * @default 'card'
    */
   container?: BannerContainer;
+  /**
+   * Resting elevation — the shadow depth the banner sits at. Use for a
+   * floating banner that hovers above content. `none` is the default inline
+   * banner.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Whether the content area (children) starts expanded.
    * Only relevant when children are provided.
@@ -215,6 +224,11 @@ const styles = stylex.create({
     flexDirection: 'column',
     fontFamily: 'inherit',
   },
+  // When elevated, a card-container banner rounds its root so the shadow
+  // follows the same silhouette as the header/content border-radius.
+  rootElevatedCard: {
+    borderRadius: radiusVars['--radius-container'],
+  },
   // Header area — colored status background with icon, title, description, actions
   // This is the primary theme target ('banner')
   header: {
@@ -323,6 +337,18 @@ const statusStyles = stylex.create({
   },
 });
 
+// Resting elevation for the banner. Applied to the root so the shadow wraps
+// the whole banner (header + optional content). 'none' is the default and
+// leaves the layout-only root untouched. For the `card` container the root is
+// rounded (rootElevatedCard) so the shadow follows the card silhouette; the
+// full-width `section` container stays square.
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {boxShadow: shadowVars['--shadow-low']},
+  med: {boxShadow: shadowVars['--shadow-med']},
+  high: {boxShadow: shadowVars['--shadow-high']},
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -381,6 +407,7 @@ export function Banner({
   onDismiss,
   endContent,
   container = 'card',
+  elevation = 'none',
   defaultIsExpanded = false,
   children,
   xstyle,
@@ -429,7 +456,16 @@ export function Banner({
     <div
       ref={ref}
       role={role}
-      {...mergeProps(stylex.props(styles.root, xstyle), className, style)}
+      {...mergeProps(
+        stylex.props(
+          styles.root,
+          elevationStyles[elevation],
+          isCard && elevation !== 'none' && styles.rootElevatedCard,
+          xstyle,
+        ),
+        className,
+        style,
+      )}
       {...rest}>
       {/* Header: colored status background — primary theme target ('banner') */}
       <div
@@ -474,8 +510,16 @@ export function Banner({
               <Button
                 variant="ghost"
                 size="sm"
-                label={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
-                tooltip={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
+                label={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
+                tooltip={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
                 icon={
                   <span
                     {...stylex.props(

package/src/Button/Button.doc.mjs

@@ -51,6 +51,13 @@ export const docs = {
       description: 'Size variant.',
       default: "'md'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth for floating buttons (e.g. a FAB). `none` is the default flat button; `low`/`med`/`high` map to the shadow token scale. Ignored inside a ButtonGroup, where elevation is owned by the group.',
+      default: "'none'",
+    },
     {
       name: 'type',
       type: "'button' | 'submit' | 'reset'",
@@ -199,6 +206,7 @@ export const docsZh = {
       default: "'secondary'",
     },
     {name: 'size', type: "'sm' | 'md' | 'lg'", description: '尺寸变体。', default: "'md'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '浮动按钮（如 FAB）的静止阴影深度。`none` 为默认扁平按钮；在 ButtonGroup 内忽略。', default: "'none'"},
     {name: 'type', type: "'button' | 'submit' | 'reset'", description: 'HTML 按钮类型属性。', default: "'button'"},
     {name: 'name', type: 'string', description: '表单提交的 HTML name 属性。'},
     {name: 'value', type: 'string | number | readonly string[]', description: '表单提交的 HTML value 属性。'},
@@ -271,6 +279,7 @@ export const docsDense = {
     label: 'accessible label; visible text by default, aria-label when isIconOnly',
     variant: 'visual style variant',
     size: 'size variant',
+    elevation: 'resting shadow depth for floating buttons/FABs: none|low|med|high; ignored inside ButtonGroup',
     type: 'HTML button type; defaults to "button"',
     name: 'HTML name for form submission',
     displayName: 'HTML name for form submission',

package/src/Button/Button.test.tsx

@@ -445,4 +445,53 @@ describe('Button', () => {
     rerender(<Button label="Submit" isLoading />);
     expect(liveRegion).toHaveTextContent('Loading');
   });
+
+  describe('elevation', () => {
+    it('renders a distinct class for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Button label="Save" elevation={elevation} />,
+        );
+        return container.querySelector('button')!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(<Button label="Save" />);
+      const {container: none} = render(
+        <Button label="Save" elevation="none" />,
+      );
+      expect(def.querySelector('button')!.className).toBe(
+        none.querySelector('button')!.className,
+      );
+    });
+  });
+
+  it('exposes aria-busy on the link-rendered button while loading', () => {
+    // Non-interruptible loading disables the button, which falls back to
+    // <button> rendering — so an anchor only shows loading when interruptible.
+    render(
+      <Button
+        label="Docs"
+        href="https://example.com"
+        isLoading
+        isInterruptible
+      />,
+    );
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('aria-busy', 'true');
+  });
+
+  it('does not set aria-busy on the link-rendered button when not loading', () => {
+    render(<Button label="Docs" href="https://example.com" />);
+    const link = screen.getByRole('link');
+    expect(link).not.toHaveAttribute('aria-busy');
+  });
 });

package/src/Button/Button.tsx

@@ -20,7 +20,7 @@
 
 import {useRef, useTransition, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
-import type {SizeValue} from '../utils/types';
+import type {Elevation, SizeValue} from '../utils/types';
 import * as stylex from '@stylexjs/stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {
@@ -33,6 +33,7 @@ import {
   easeVars,
   fontWeightVars,
   typeScaleVars,
+  shadowVars,
 } from '../theme/tokens.stylex';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -160,6 +161,18 @@ const iconSizeStyles = stylex.create({
   lg: {width: 20, height: 20, fontSize: 20},
 });
 
+/**
+ * Resting elevation for floating buttons (e.g. a FAB). `none` is the default
+ * flat button; `low`/`med`/`high` map to the shadow token scale. 'none' stays
+ * a literal so it never conflicts with a variant's background layering.
+ */
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {boxShadow: shadowVars['--shadow-low']},
+  med: {boxShadow: shadowVars['--shadow-med']},
+  high: {boxShadow: shadowVars['--shadow-high']},
+});
+
 /**
  * Variant styles using backgroundImage for layered colors
  * Pseudo-classes are nested within properties per StyleX recommendation
@@ -307,6 +320,12 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
    * @default 'md'
    */
   size?: ButtonSize;
+  /**
+   * Resting elevation — the shadow depth the button sits at. Use for floating
+   * buttons (FABs) that hover above content. `none` is the default flat button.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Whether the button is disabled.
    * @default false
@@ -578,6 +597,7 @@ export function Button({
   icon,
   isIconOnly = false,
   width,
+  elevation = 'none',
   children,
   endContent,
   tooltip,
@@ -691,6 +711,9 @@ export function Button({
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.onSolidHorizontal
         : groupStyles.onSolidVertical),
+    // Standalone floating buttons only — a grouped button's elevation is owned
+    // by the ButtonGroup so the shared surface lifts as one unit.
+    !buttonGroup && elevationStyles[elevation],
     width != null && dynamicStyles.width(width),
     xstyle,
   );
@@ -786,6 +809,7 @@ export function Button({
         {...ariaLabelProp}
         {...describedByProp}
         {...edgeCompAttr}
+        aria-busy={isLoadingState || undefined}
         onClick={handleClick}>
         {buttonContent}
       </LinkComponent>

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -29,6 +29,7 @@ export const docs = {
         {name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},
         {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},
         {name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},
+        {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth for the whole group. The connected buttons share one surface, so the shadow lifts them as a unit. Use for a group that floats above content.', default: "'none'"},
         {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
         {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
         {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
@@ -66,6 +67,7 @@ export const docsZh = {
         orientation: '按钮组的布局方向。',
         size: '组内按钮的默认尺寸。单个按钮可覆盖。',
         isDisabled: '组内所有按钮是否禁用。',
+        elevation: '整个组的静止阴影深度。连接的按钮共享一个表面，阴影将它们作为整体抬起。',
         ref: '转发到根元素的引用。',
         xstyle: 'StyleX 样式，用于布局自定义。必须是 stylex.create() 的值。',
         'data-testid': '自动化测试的选择器。',
@@ -116,6 +118,7 @@ export const docsDense = {
         orientation: 'layout direction',
         size: 'default btn size; individual btns override',
         isDisabled: 'all btns disabled',
+        elevation: 'resting shadow depth for whole group: none|low|med|high',
         xstyle: 'StyleX layout styles; must be stylex.create() value',
         'data-testid': 'test selector',
       },

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -572,4 +572,41 @@ describe('ButtonGroup', () => {
       expect(hasRoundedTrailingCorners(save)).toBe(false);
     });
   });
+
+  describe('elevation', () => {
+    it('renders a distinct class on the group for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <ButtonGroup label="Actions" elevation={elevation}>
+            <Button label="One" />
+            <Button label="Two" />
+          </ButtonGroup>,
+        );
+        return container.querySelector('[role="group"]')!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <ButtonGroup label="Actions">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+      const {container: none} = render(
+        <ButtonGroup label="Actions" elevation="none">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+      expect(def.querySelector('[role="group"]')!.className).toBe(
+        none.querySelector('[role="group"]')!.className,
+      );
+    });
+  });
 });

package/src/ButtonGroup/ButtonGroup.tsx

@@ -24,6 +24,8 @@
 import {useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {ButtonSize} from '../Button';
+import {radiusVars, shadowVars} from '../theme/tokens.stylex';
+import type {Elevation} from '../utils/types';
 import {SizeProvider, useSize} from '../SizeContext/SizeContext';
 import {useListFocus} from '../hooks/useListFocus';
 import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
@@ -63,6 +65,14 @@ export interface ButtonGroupProps extends BaseProps<HTMLDivElement> {
    */
   size?: ButtonSize;
 
+  /**
+   * Resting elevation for the group. The connected buttons share one surface,
+   * so the shadow sits on the group and lifts them together. Use for a floating
+   * group of actions above content.
+   * @default 'none'
+   */
+  elevation?: Elevation;
+
   /**
    * Whether all buttons in the group are disabled.
    * @default false
@@ -89,6 +99,26 @@ const styles = stylex.create({
   },
 });
 
+// Resting elevation for the whole group — the connected buttons share one
+// surface, so the shadow sits on the group wrapper and lifts them as a unit.
+// The wrapper takes the element radius so the shadow follows the group's
+// rounded outer corners rather than a bare rectangle. 'none' is the default.
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {
+    boxShadow: shadowVars['--shadow-low'],
+    borderRadius: radiusVars['--radius-element'],
+  },
+  med: {
+    boxShadow: shadowVars['--shadow-med'],
+    borderRadius: radiusVars['--radius-element'],
+  },
+  high: {
+    boxShadow: shadowVars['--shadow-high'],
+    borderRadius: radiusVars['--radius-element'],
+  },
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -129,6 +159,7 @@ export function ButtonGroup({
   orientation = 'horizontal',
   size: sizeProp,
   isDisabled = false,
+  elevation = 'none',
   xstyle,
   className,
   style,
@@ -160,6 +191,7 @@ export function ButtonGroup({
             stylex.props(
               styles.group,
               orientation === 'vertical' && styles.vertical,
+              elevationStyles[elevation],
               xstyle,
             ),
             className,

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

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