@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/AspectRatio/AspectRatio.tsx

@@ -5,12 +5,13 @@
 /**
  * @file AspectRatio.tsx
  * @input Uses React, stylex
- * @output Exports AspectRatio component and AspectRatioProps
+ * @output Exports AspectRatio component, AspectRatioProps, AspectRatioShape, AspectRatioFit
  * @position AspectRatio component; maintains a specific aspect ratio for its children
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
+ * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
  * - /packages/cli/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
@@ -29,6 +30,16 @@ import {themeProps} from '../utils/themeProps';
  */
 export type AspectRatioShape = 'rectangle' | 'ellipse';
 
+/**
+ * How the child is sized and positioned inside the ratio box.
+ * - `cover`: the child fills the box; media is cropped to preserve its own
+ *   aspect ratio (`object-fit: cover`).
+ * - `contain`: the child fills the box; media is letterboxed to stay fully
+ *   visible (`object-fit: contain`).
+ * - `center`: the child keeps its natural size and sits centered in the box.
+ */
+export type AspectRatioFit = 'cover' | 'contain' | 'center';
+
 export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -41,20 +52,45 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
    * The shape of the container. Both shapes respect the provided `ratio`.
    * - `rectangle` (default): a standard rectangular container.
    * - `ellipse`: clips the container to an ellipse — a circle when `ratio={1}`,
-   *   or an oval at other ratios. Pair with a child that fills the container
-   *   (e.g. an image with `objectFit: 'cover'`).
+   *   or an oval at other ratios. Pair with `fit="cover"` so the media fills
+   *   the clipped container.
    *
    * @default 'rectangle'
    *
    * @example
    * ```
-   * <AspectRatio ratio={1} shape="ellipse">
-   *   <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+   * <AspectRatio ratio={1} shape="ellipse" fit="cover">
+   *   <img src="avatar.jpg" alt="" />
    * </AspectRatio>
    * ```
    */
   shape?: AspectRatioShape;
 
+  /**
+   * How the child is laid out inside the ratio box, so the child does not
+   * have to declare `width`/`height`/`objectFit` itself.
+   * - `cover`: child fills the box; media is cropped (`object-fit: cover`).
+   * - `contain`: child fills the box; media is letterboxed
+   *   (`object-fit: contain`).
+   * - `center`: child keeps its natural size, centered in the box.
+   *
+   * `cover`/`contain` child sizing ships as zero-specificity baseline rules
+   * in `reset.css`, keyed on the `data-astryx-aspect-ratio-override`
+   * attribute the component sets on the child's direct parent. Any styles
+   * the child sets itself still win, so children that already size
+   * themselves keep their behavior. When omitted, the child is left
+   * unstyled (the pre-existing contract). `fit` is structural, not visual,
+   * so it is not exposed on the theming surface.
+   *
+   * @example
+   * ```
+   * <AspectRatio ratio={16 / 9} fit="cover">
+   *   <img src="image.jpg" alt="Widescreen image" />
+   * </AspectRatio>
+   * ```
+   */
+  fit?: AspectRatioFit;
+
   /**
    * Content to render inside the aspect ratio container.
    * The child element will be positioned absolutely to fill the container.
@@ -82,6 +118,16 @@ const styles = stylex.create({
     width: '100%',
     height: '100%',
   },
+  // fit="center" centers the child at its natural size from the wrapper —
+  // no styles on the child itself. The `cover`/`contain` child sizing can't
+  // live here (StyleX has no descendant selectors); it ships as baseline
+  // rules in reset.css keyed on the `data-astryx-aspect-ratio-override`
+  // attribute the wrapper carries (see below).
+  childCenter: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
 });
 
 /**
@@ -91,27 +137,32 @@ const styles = stylex.create({
  * is positioned absolutely to fill the container, which is useful for images,
  * videos, embeds, and placeholders.
  *
+ * Use `fit` to let the component size the child: `cover`/`contain` stretch
+ * the child to fill the box (cropping or letterboxing media), `center` keeps
+ * the child at its natural size. Without `fit`, the child styles itself.
+ *
  * Use `shape="ellipse"` to clip the container into an ellipse — a circle at
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
  * @example
  * ```
- * <AspectRatio ratio={16 / 9}>
- *   <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />
+ * <AspectRatio ratio={16 / 9} fit="cover">
+ *   <img src="image.jpg" alt="Widescreen image" />
  * </AspectRatio>
  * ```
  *
  * @example
  * ```
- * <AspectRatio ratio={1} shape="ellipse">
- *   <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+ * <AspectRatio ratio={1} shape="ellipse" fit="cover">
+ *   <img src="avatar.jpg" alt="" />
  * </AspectRatio>
  * ```
  */
 export function AspectRatio({
   ratio,
   shape = 'rectangle',
+  fit,
   children,
   xstyle,
   className,
@@ -133,7 +184,16 @@ export function AspectRatio({
         {...style, aspectRatio: ratio},
       )}
       {...props}>
-      <div {...stylex.props(styles.child)}>{children}</div>
+      {/* The marker attribute carries the fit value so the reset.css child
+          sizing can use direct-child selectors on this wrapper — the child's
+          actual parent — without depending on AspectRatio's internal
+          structure or on the theming surface (fit is structural, not
+          themeable). The name is namespaced to avoid collisions. */}
+      <div
+        data-astryx-aspect-ratio-override={fit}
+        {...stylex.props(styles.child, fit === 'center' && styles.childCenter)}>
+        {children}
+      </div>
     </div>
   );
 }

package/src/AspectRatio/index.ts

@@ -12,4 +12,8 @@
  */
 
 export {AspectRatio} from './AspectRatio';
-export type {AspectRatioProps, AspectRatioShape} from './AspectRatio';
+export type {
+  AspectRatioProps,
+  AspectRatioShape,
+  AspectRatioFit,
+} from './AspectRatio';

package/src/Avatar/Avatar.doc.mjs

@@ -106,4 +106,15 @@ export const docsDense = {
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],
   },
+  propDescriptions: {
+    src: 'primary image source URL',
+    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.",
+    status: 'corner content for status indicators',
+  },
+  components: [
+    {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},
+  ],
 };

package/src/Avatar/Avatar.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import {Avatar} from './Avatar';
 
 describe('Avatar', () => {
@@ -34,4 +34,35 @@ describe('Avatar', () => {
     // The inner <img> carries an empty alt so it isn't announced separately.
     expect(innerImg).toHaveAttribute('alt', '');
   });
+
+  it('retries a new src after a previous src failed to load', () => {
+    const {rerender} = render(
+      <Avatar name="Ada" src="https://example.com/broken.jpg" />,
+    );
+    const wrapper = screen.getByRole('img', {name: 'Ada'});
+    fireEvent.error(wrapper.querySelector('img')!);
+    // Broken image falls back to initials.
+    expect(wrapper.querySelector('img')).toBeNull();
+    expect(wrapper).toHaveTextContent('A');
+
+    // A different src must get a fresh load attempt, not the stale error.
+    rerender(<Avatar name="Ada" src="https://example.com/ada.jpg" />);
+    const img = wrapper.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
+  });
+
+  it('retries a new fallbackSrc after a previous fallbackSrc failed to load', () => {
+    const {rerender} = render(
+      <Avatar name="Ada" fallbackSrc="https://example.com/broken.jpg" />,
+    );
+    const wrapper = screen.getByRole('img', {name: 'Ada'});
+    fireEvent.error(wrapper.querySelector('img')!);
+    expect(wrapper.querySelector('img')).toBeNull();
+
+    rerender(<Avatar name="Ada" fallbackSrc="https://example.com/ada.jpg" />);
+    const img = wrapper.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
+  });
 });

package/src/Avatar/Avatar.tsx

@@ -63,20 +63,7 @@ type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
  * Numeric size options (in pixels)
  */
 type AvatarNumericSize =
-  | 16
-  | 20
-  | 24
-  | 32
-  | 36
-  | 40
-  | 48
-  | 60
-  | 64
-  | 72
-  | 96
-  | 128
-  | 144
-  | 180;
+  16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180;
 
 /**
  * Avatar size - can be a named size or a specific pixel value
@@ -289,11 +276,16 @@ export function Avatar({
   ref,
   ...props
 }: AvatarProps) {
-  const [imageError, setImageError] = useState(false);
-  const [fallbackError, setFallbackError] = useState(false);
+  // Track the exact src that failed (rather than a boolean) so a changed
+  // src/fallbackSrc gets a fresh load attempt instead of the stale error.
+  const [erroredSrc, setErroredSrc] = useState<string | undefined>(undefined);
+  const [erroredFallbackSrc, setErroredFallbackSrc] = useState<
+    string | undefined
+  >(undefined);
 
-  const showImage = src && !imageError;
-  const showFallbackImage = !showImage && fallbackSrc && !fallbackError;
+  const showImage = src && erroredSrc !== src;
+  const showFallbackImage =
+    !showImage && fallbackSrc && erroredFallbackSrc !== fallbackSrc;
   const showInitials = !showImage && !showFallbackImage && name;
   const showIcon = !showImage && !showFallbackImage && !name;
 
@@ -309,6 +301,7 @@ export function Avatar({
   return (
     <AvatarSizeContext value={numericSize}>
       <div
+        {...props}
         ref={ref}
         role={isDecorative ? 'presentation' : 'img'}
         aria-label={isDecorative ? undefined : accessibleName}
@@ -325,14 +318,13 @@ export function Avatar({
           ),
           className,
           style,
-        )}
-        {...props}>
+        )}>
         <div {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
           {showImage && (
             <img
               src={src}
               alt=""
-              onError={() => setImageError(true)}
+              onError={() => setErroredSrc(src)}
               {...stylex.props(styles.image)}
             />
           )}
@@ -340,7 +332,7 @@ export function Avatar({
             <img
               src={fallbackSrc}
               alt=""
-              onError={() => setFallbackError(true)}
+              onError={() => setErroredFallbackSrc(fallbackSrc)}
               {...stylex.props(styles.image)}
             />
           )}

package/src/Avatar/AvatarStatusDot.tsx

@@ -193,6 +193,7 @@ export function AvatarStatusDot({
 
   return (
     <div
+      {...props}
       ref={ref}
       {...(label ? {role: 'img', 'aria-label': label} : undefined)}
       {...mergeProps(
@@ -205,8 +206,7 @@ export function AvatarStatusDot({
         ),
         className,
         style,
-      )}
-      {...props}>
+      )}>
       {icon && iconSize > 0 && (
         <span
           aria-hidden="true"

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -24,6 +24,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-avatar-group', visualProps: ['size']},
+      {className: 'astryx-avatar-group-overflow'},
     ],
   },
   description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.',

package/src/AvatarGroup/AvatarGroup.tsx

@@ -94,6 +94,7 @@ export function AvatarGroup({
   return (
     <AvatarGroupContext value={contextValue}>
       <div
+        {...props}
         ref={ref}
         role="group"
         aria-label={ariaLabel}
@@ -103,8 +104,7 @@ export function AvatarGroup({
           stylex.props(styles.root, xstyle),
           className,
           style,
-        )}
-        {...props}>
+        )}>
         {children}
       </div>
     </AvatarGroupContext>

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -147,8 +147,8 @@ export function AvatarGroupOverflow({
         ref={ref as React.Ref<HTMLButtonElement>}
         type="button"
         onClick={onClick}
-        aria-label={label}
         {...rest}
+        aria-label={label}
         {...mergeProps(
           themeProps('avatar-group-overflow'),
           stylex.props(
@@ -171,8 +171,8 @@ export function AvatarGroupOverflow({
   return (
     <span
       ref={ref}
-      aria-label={label}
       {...rest}
+      aria-label={label}
       {...mergeProps(
         themeProps('avatar-group-overflow'),
         stylex.props(

package/src/Banner/Banner.doc.mjs

@@ -113,6 +113,7 @@ export const docs = {
     targets: [
       {className: 'astryx-banner', visualProps: ['container', 'status']},
       {className: 'astryx-banner-icon', visualProps: ['status']},
+      {className: 'astryx-banner-content', visualProps: ['container', 'status']},
     ],
     vars: [
       {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},
@@ -180,6 +181,13 @@ export const docsZh = {
           'status',
         ],
       },
+      {
+        className: 'astryx-banner-content',
+        visualProps: [
+          'container',
+          'status',
+        ],
+      },
     ],
     vars: [
       {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},

package/src/Banner/Banner.test.tsx

@@ -270,6 +270,44 @@ describe('Banner', () => {
     expect(expandIndex).toBeLessThan(dismissIndex);
   });
 
+  it('links the expand toggle to its content region via aria-controls', () => {
+    render(
+      <Banner status="info" title="Controls Test" defaultIsExpanded>
+        <div data-testid="region-content">Region content</div>
+      </Banner>,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Collapse'});
+    const controlsId = toggle.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real content region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByTestId('region-content'));
+  });
+
+  it('sets aria-controls only while the content region is mounted', async () => {
+    const user = userEvent.setup();
+    render(
+      <Banner status="info" title="Controls Toggle">
+        <div data-testid="region-content">Region content</div>
+      </Banner>,
+    );
+
+    // Collapsed: the region is unmounted, so no dangling aria-controls target.
+    const collapsedToggle = screen.getByRole('button', {name: 'Expand'});
+    expect(collapsedToggle).not.toHaveAttribute('aria-controls');
+
+    // Expanded: aria-controls resolves to the mounted region with the children.
+    await user.click(collapsedToggle);
+    const expandedToggle = screen.getByRole('button', {name: 'Collapse'});
+    const controlsId = expandedToggle.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByTestId('region-content'));
+  });
+
   it('does not render content area when no children', () => {
     const {container} = render(<Banner status="info" title="No Children" />);
     const root = container.firstElementChild;

package/src/Banner/Banner.tsx

@@ -31,7 +31,7 @@
  * - /packages/cli/templates/blocks/components/Banner/ (showcase blocks)
  */
 
-import {useState, type ReactNode} from 'react';
+import {useId, useState, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {Button} from '../Button';
@@ -387,6 +387,11 @@ export function Banner({
 }: BannerProps) {
   const [isDismissed, setIsDismissed] = useState(false);
   const [isExpanded, setIsExpanded] = useState(defaultIsExpanded);
+  // Links the expand/collapse toggle to the content region it shows/hides so
+  // assistive tech can move from the button to its controlled content
+  // (disclosure pattern). The region is conditionally rendered, so aria-controls
+  // below is set only while it's mounted to avoid a dangling reference.
+  const contentId = useId();
   const defaultIconName = defaultIconNames[status];
   const role = statusRole[status];
   const iconColor = statusIconColor[status];
@@ -477,6 +482,7 @@ export function Banner({
                 }
                 onClick={handleToggleExpand}
                 aria-expanded={isExpanded}
+                aria-controls={showContent ? contentId : undefined}
                 isIconOnly
               />
             )}
@@ -497,6 +503,7 @@ export function Banner({
       {/* Content area: collapsible card background — theme target ('banner-content') */}
       {showContent && (
         <div
+          id={contentId}
           {...mergeProps(
             themeProps('banner-content', {container, status}),
             stylex.props(styles.contentArea, isCard && styles.contentAreaCard),

package/src/Calendar/Calendar.doc.mjs

@@ -19,7 +19,7 @@ export const docs = {
       {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
     ],
     anatomy: [
-      {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months.'},
+      {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".'},
       {name: 'Day grid', required: true, description: 'A 7-column grid of days with column headers for the day names.'},
       {name: 'Selected day', required: false, description: 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.'},
       {name: 'Today marker', required: false, description: 'A subtle indicator on the current date for orientation.'},