@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Avatar/Avatar.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Avatar.tsx
  * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
- *   (Tooltip hook) for the optional name-on-hover tooltip
+ *   (Tooltip hook) for the optional name-on-hover tooltip; useTranslator (i18n)
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
  *
@@ -14,9 +14,11 @@
  * - /packages/core/src/Avatar/index.ts (exports if types change)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Avatar/ (showcase blocks)
+ *
+ * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
 
-import {useMemo, useState, type ReactNode} from 'react';
+import {isValidElement, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -30,6 +32,9 @@ import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTooltip} from '../Tooltip/useTooltip';
+import {useLinkComponent} from '../Link/useLinkComponent';
+import type {LinkComponentType} from '../Link/types';
+import {useTranslator} from '../i18n';
 
 /**
  * The offset ratio for positioning elements on a circle's edge at 45°.
@@ -61,7 +66,7 @@ const INITIALS_FONT_SIZE_RATIO = 0.4;
  *
  * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
  * but the values are larger because avatars align with media rather than
- * glyphs. The tiers match EPS's avatar sizes.
+ * glyphs. The tiers follow the standard avatar size scale.
  */
 type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 
@@ -106,6 +111,11 @@ const styles = stylex.create({
     position: 'relative',
     display: 'inline-flex',
     flexShrink: 0,
+    // The wrapper is not clipped (so the status dot can overflow), so it must be
+    // rounded itself: a themed fallback background lands on `.astryx-avatar` (the
+    // class-bearing wrapper) as well as the internal var, and an unrounded
+    // wrapper would show that fill as square corners behind the circular content.
+    borderRadius: radiusVars['--radius-full'],
   },
   content: {
     display: 'flex',
@@ -126,10 +136,14 @@ const styles = stylex.create({
     justifyContent: 'center',
     width: '100%',
     height: '100%',
-    backgroundColor: colorVars['--color-neutral'],
-    color: colorVars['--color-text-secondary'],
+    // Fallback surface (initials + default icon). Each property reads an
+    // Avatar-scoped internal var so a theme can re-scope the fallback wash and
+    // initials weight/color without forking; the defaults reproduce today's
+    // exact output. See derivedVarRegistry (avatar) + Avatar.doc.mjs theming.
+    backgroundColor: `var(--_avatar-fallback-background, ${colorVars['--color-neutral']})`,
+    color: `var(--_avatar-fallback-color, ${colorVars['--color-text-secondary']})`,
     fontFamily: typographyVars['--font-family-body'],
-    fontWeight: fontWeightVars['--font-weight-medium'],
+    fontWeight: `var(--_avatar-fallback-font-weight, ${fontWeightVars['--font-weight-medium']})`,
     textTransform: 'uppercase',
   },
   status: {
@@ -148,6 +162,39 @@ const styles = stylex.create({
       ':focus-visible': '2px',
     },
   },
+  // 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.
+  interactive: {
+    appearance: 'none',
+    padding: 0,
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    backgroundColor: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    textDecoration: 'none',
+    cursor: 'pointer',
+    // Match the avatar's circular shape so the focus ring hugs it.
+    borderRadius: radiusVars['--radius-full'],
+    outlineWidth: {
+      default: 0,
+      ':focus-visible': 2,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':focus-visible': 'solid',
+    },
+    outlineColor: {
+      default: null,
+      ':focus-visible': colorVars['--color-accent'],
+    },
+    outlineOffset: {
+      default: 0,
+      ':focus-visible': 2,
+    },
+  },
 });
 
 /**
@@ -158,8 +205,13 @@ const dynamicStyles = stylex.create({
     width: size,
     height: size,
   }),
+  // Initials font size defaults to the proportional `size × ratio` scale but is
+  // reachable via the `--_avatar-fallback-font-size` derived var, so a theme can
+  // set a per-size type scale (e.g. `components.avatar['size:sm']`).
   fontSize: (size: number) => ({
-    fontSize: size * INITIALS_FONT_SIZE_RATIO,
+    fontSize: `var(--_avatar-fallback-font-size, ${
+      size * INITIALS_FONT_SIZE_RATIO
+    }px)`,
   }),
   statusPosition: (size: number) => ({
     bottom: size * CIRCLE_EDGE_OFFSET_RATIO,
@@ -229,6 +281,11 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
   /**
    * Content displayed in the corner of the avatar.
    * Typically used for status indicators or badges.
+   *
+   * When the element carries a string `label` prop (as `AvatarStatusDot`
+   * does), the label is composed into the avatar's accessible name
+   * (e.g. "Jane Doe, Online") so assistive tech can reach the status —
+   * the `role="img"` root prunes descendant semantics (WCAG 4.1.2).
    */
   status?: ReactNode;
   /**
@@ -244,6 +301,35 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    * @default true
    */
   tooltip?: string | boolean;
+  /**
+   * When provided, the avatar becomes an interactive link (`<a>` or custom
+   * link component) pointing at `href`. Follows the same element-swap rules as
+   * Button: `href` renders a link, otherwise `onClick` renders a
+   * `<button type="button">`, otherwise the avatar stays a static (non-focusable)
+   * element. An interactive avatar requires a meaningful accessible name via
+   * `alt` or `name`.
+   */
+  href?: string;
+  /**
+   * Custom link component to use when `href` is provided. Overrides the
+   * provider-level default set by LinkProvider. Useful for Next.js `<Link>` or
+   * other router-aware components. Only applies when `href` is provided.
+   */
+  as?: LinkComponentType;
+  /**
+   * HTML target attribute for the link. Only applies when `href` is provided.
+   */
+  target?: string;
+  /**
+   * HTML rel attribute for the link. Only applies when `href` is provided.
+   */
+  rel?: string;
+  /**
+   * Click handler. When provided without `href`, renders the avatar as a
+   * focusable `<button type="button">`. An interactive avatar requires a
+   * meaningful accessible name via `alt` or `name`.
+   */
+  onClick?: React.MouseEventHandler<HTMLElement>;
 }
 
 /**
@@ -266,6 +352,24 @@ function getInitials(name: string): string {
   return (words[0].charAt(0) + words[words.length - 1].charAt(0)).toUpperCase();
 }
 
+/**
+ * Reads the accessible status label off the `status` element, when it
+ * exposes one. `AvatarStatusDot`'s `label` prop is the canonical source,
+ * but any custom status element with a string `label` prop participates.
+ *
+ * The avatar root is `role="img"`, which prunes ALL descendant semantics
+ * from the accessibility tree — a label inside the status subtree is never
+ * announced on its own. Composing it into the avatar's own accessible name
+ * is the only way the status reaches assistive tech (WCAG 4.1.2).
+ */
+function getStatusLabel(status: ReactNode): string | undefined {
+  if (!isValidElement(status)) {
+    return undefined;
+  }
+  const {label} = status.props as {label?: unknown};
+  return typeof label === 'string' && label !== '' ? label : undefined;
+}
+
 /**
  * Default person icon SVG for when no image or name is provided
  */
@@ -295,6 +399,8 @@ function DefaultIcon({size}: {size: number}) {
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * <Avatar name="jsmith" tooltip="Jane Smith, Staff Engineer" />
  * <Avatar name="Jane" tooltip={false} />
+ * <Avatar src="/user.jpg" name="John Doe" href="/users/john" />
+ * <Avatar src="/user.jpg" name="John Doe" onClick={() => openProfile()} />
  * ```
  */
 export function Avatar({
@@ -306,6 +412,11 @@ export function Avatar({
   src,
   status,
   tooltip = true,
+  href,
+  as,
+  target,
+  rel,
+  onClick,
   xstyle,
   className,
   style,
@@ -325,10 +436,24 @@ export function Avatar({
   const showInitials = !showImage && !showFallbackImage && name;
   const showIcon = !showImage && !showFallbackImage && !name;
 
-  // A meaningful accessible name comes from `alt` or `name`. With neither, the
-  // avatar is decorative — expose it as `presentation`/`aria-hidden` rather than
-  // announcing a meaningless generic "Avatar" (obs-9).
-  const accessibleName = alt || name;
+  // A meaningful accessible name comes from `alt`/`name`, composed with the
+  // status element's `label` when one is present ("Jane Doe, Online") — the
+  // `role="img"` root prunes descendant semantics, so surfacing the label in
+  // the avatar's own name is the only way assistive tech can reach the
+  // status (WCAG 4.1.2). A labelled status alone is also meaningful. With
+  // neither a name nor a labelled status, the avatar is decorative — expose
+  // it as `presentation`/`aria-hidden` rather than announcing a meaningless
+  // generic "Avatar" (obs-9).
+  const t = useTranslator();
+  const nameLabel = alt || name;
+  const statusLabel = getStatusLabel(status);
+  const accessibleName =
+    nameLabel && statusLabel
+      ? t('@astryx.avatar.nameWithStatus', {
+          name: nameLabel,
+          status: statusLabel,
+        })
+      : nameLabel || statusLabel;
   const isDecorative = !accessibleName;
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
@@ -359,11 +484,14 @@ export function Avatar({
   // returns `describedBy` as a value we choose whether to apply — the only way
   // to satisfy the per-case aria-describedby rule (default name: none; custom
   // string: describe) without editing Tooltip. `focusTrigger: 'auto'` shows the
-  // tooltip on keyboard focus once the root is made focusable (below).
+  // tooltip on keyboard focus once the root is focusable (natively for the
+  // interactive <a>/<button>, or via an explicit tab stop on the static div).
   const tooltipHook = useTooltip({
     placement: 'above',
     isEnabled: showTooltip,
   });
+  // The tooltip ref attaches to whichever root element renders (static or
+  // interactive), so the tooltip works for link/button avatars too.
   const rootRef = mergeRefs(ref, showTooltip ? tooltipHook.ref : undefined);
   const describedByProp =
     showTooltip && isCustomTooltip
@@ -375,8 +503,136 @@ export function Avatar({
         }
       : null;
 
-  const avatarElement = (
-    <AvatarSizeContext value={numericSize}>
+  // Element-swap trichotomy, copied from Button: `href` renders a link,
+  // otherwise `onClick` renders a `<button>`, otherwise today's static element
+  // is unchanged (the non-breaking default).
+  const renderAsLink = href != null;
+  const renderAsButton = !renderAsLink && onClick != null;
+  const isInteractive = renderAsLink || renderAsButton;
+  const LinkComponent = useLinkComponent(as);
+
+  // An interactive control with no accessible name is an unacceptable control
+  // name. Warn in the same client-safe way sibling components do (Field,
+  // Timestamp, Popover) — a plain `console.warn`, never gated on `process.env`
+  // (which is not available on the client in this codebase).
+  if (isInteractive && !accessibleName) {
+    console.warn(
+      'Avatar: an interactive avatar (with `href` or `onClick`) needs a ' +
+        'meaningful accessible name. Pass `alt` or `name`.',
+    );
+  }
+
+  // The inner visuals are identical across the static and interactive variants.
+  const visualContent = (
+    <>
+      <div {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
+        {showImage && (
+          <img
+            src={src}
+            alt=""
+            onError={() => setErroredSrc(src)}
+            {...stylex.props(styles.image)}
+          />
+        )}
+        {showFallbackImage && (
+          <img
+            src={fallbackSrc}
+            alt=""
+            onError={() => setErroredFallbackSrc(fallbackSrc)}
+            {...stylex.props(styles.image)}
+          />
+        )}
+        {showInitials && (
+          <div
+            {...stylex.props(
+              styles.fallback,
+              dynamicStyles.fontSize(numericSize),
+            )}>
+            {getInitials(name)}
+          </div>
+        )}
+        {showIcon && (
+          <div {...stylex.props(styles.fallback)}>
+            <DefaultIcon size={numericSize} />
+          </div>
+        )}
+      </div>
+      {status && (
+        <div
+          {...stylex.props(
+            styles.status,
+            dynamicStyles.statusPosition(numericSize),
+          )}>
+          {status}
+        </div>
+      )}
+    </>
+  );
+
+  // Shared StyleX + theme props for the root element in every variant. The
+  // group ring/overlap, the interactive focus-visible ring, and the
+  // 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}),
+    stylex.props(
+      styles.wrapper,
+      isInteractive && styles.interactive,
+      !isInteractive && showTooltip && !avatarGroup && styles.focusable,
+      avatarGroup && groupStyles.ring,
+      avatarGroup && groupStyles.overlap,
+      avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),
+      xstyle,
+    ),
+    className,
+    style,
+  );
+
+  let rootElement: ReactNode;
+
+  // `props` is typed for the default `<div>` root (its event handlers are
+  // HTMLDivElement-typed). The interactive branches render an `<a>`/`<button>`,
+  // so the passthrough props are re-typed to the generic element here — the
+  // avatar's own handlers (onClick) are declared on HTMLElement and stay typed.
+  const interactivePassthrough = props as React.HTMLAttributes<HTMLElement>;
+
+  if (renderAsLink) {
+    // The rendered link carries the `data-avatar-item` marker so AvatarGroup's
+    // roving focus (which selects on `[data-avatar-item]`, not a tag/role) picks
+    // it up while ignoring nested buttons in a custom status/badge slot.
+    rootElement = (
+      <LinkComponent
+        {...interactivePassthrough}
+        {...describedByProp}
+        ref={rootRef as React.Ref<HTMLAnchorElement>}
+        href={href}
+        target={target}
+        rel={rel}
+        aria-label={accessibleName}
+        data-avatar-item=""
+        data-testid={testId}
+        onClick={onClick}
+        {...rootStylexProps}>
+        {visualContent}
+      </LinkComponent>
+    );
+  } else if (renderAsButton) {
+    rootElement = (
+      <button
+        {...interactivePassthrough}
+        {...describedByProp}
+        ref={rootRef}
+        type="button"
+        aria-label={accessibleName}
+        data-avatar-item=""
+        data-testid={testId}
+        onClick={onClick}
+        {...rootStylexProps}>
+        {visualContent}
+      </button>
+    );
+  } else {
+    rootElement = (
       <div
         {...props}
         ref={rootRef}
@@ -385,79 +641,29 @@ export function Avatar({
         aria-hidden={isDecorative || undefined}
         // The root is a div[role="img"], not natively focusable. When a name
         // tooltip is active, add a tab stop so keyboard users can reveal it
-        // (WCAG 1.4.13 / 2.1.1) — matching Timestamp/Button. Only while active.
-        tabIndex={showTooltip ? 0 : undefined}
+        // (WCAG 1.4.13 / 2.1.1) — matching Timestamp/Button. Suppressed inside
+        // an AvatarGroup, which owns a single roving tab stop for its members.
+        tabIndex={showTooltip && !avatarGroup ? 0 : undefined}
         data-testid={testId}
         {...describedByProp}
-        {...mergeProps(
-          themeProps('avatar', {size: resolvedSize}),
-          stylex.props(
-            styles.wrapper,
-            showTooltip && styles.focusable,
-            avatarGroup && groupStyles.ring,
-            avatarGroup && groupStyles.overlap,
-            avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),
-            xstyle,
-          ),
-          className,
-          style,
-        )}>
-        <div {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
-          {showImage && (
-            <img
-              src={src}
-              alt=""
-              onError={() => setErroredSrc(src)}
-              {...stylex.props(styles.image)}
-            />
-          )}
-          {showFallbackImage && (
-            <img
-              src={fallbackSrc}
-              alt=""
-              onError={() => setErroredFallbackSrc(fallbackSrc)}
-              {...stylex.props(styles.image)}
-            />
-          )}
-          {showInitials && (
-            <div
-              {...stylex.props(
-                styles.fallback,
-                dynamicStyles.fontSize(numericSize),
-              )}>
-              {getInitials(name)}
-            </div>
-          )}
-          {showIcon && (
-            <div {...stylex.props(styles.fallback)}>
-              <DefaultIcon size={numericSize} />
-            </div>
-          )}
-        </div>
-        {status && (
-          <div
-            {...stylex.props(
-              styles.status,
-              dynamicStyles.statusPosition(numericSize),
-            )}>
-            {status}
-          </div>
-        )}
+        {...rootStylexProps}>
+        {visualContent}
       </div>
-    </AvatarSizeContext>
-  );
-
-  if (!showTooltip) {
-    return avatarElement;
+    );
   }
 
-  // Render the tooltip as a sibling (no wrapper DOM) — the hook's ref is already
-  // attached to the root via `rootRef` above. `trimmedTooltip` is guaranteed
-  // non-empty here.
+  const avatarElement = (
+    <AvatarSizeContext value={numericSize}>{rootElement}</AvatarSizeContext>
+  );
+
+  // Always return the same structure so the avatar keeps its position in the
+  // React tree regardless of the tooltip flag — toggling it must not remount
+  // the avatar subtree (and lose image-load state). The tooltip is a sibling
+  // (no wrapper DOM); the hook's ref is already on the root via `rootRef`.
   return (
     <>
       {avatarElement}
-      {tooltipHook.renderTooltip(trimmedTooltip)}
+      {showTooltip ? tooltipHook.renderTooltip(trimmedTooltip) : null}
     </>
   );
 }

package/src/Avatar/AvatarStatusDot.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
       name: 'label',
       type: 'string',
       description:
-        'Accessible label describing the status. Not announced inside an Avatar today (the Avatar root is role="img", which prunes child semantics) — pass it anyway; an Avatar-level name-composition fix is planned.',
+        'Accessible label describing the status. Inside an Avatar it is composed into the avatar\'s accessible name (e.g. "Jane Doe, Online"); the Avatar root is role="img", which prunes child semantics, so the composed name is how the status reaches assistive tech. Standalone dots expose role="img" with this label directly.',
     },
     {
       name: 'icon',
@@ -59,7 +59,7 @@ export const docsZh = {
       name: 'label',
       type: 'string',
       description:
-        '描述状态的无障碍标签。目前在 Avatar 内不会被朗读（Avatar 根元素为 role="img"，会裁剪子元素语义）——仍请传入；Avatar 层面的名称合成修复已在计划中。',
+        '描述状态的无障碍标签。在 Avatar 内会被合成进头像自身的无障碍名称（如 "Jane Doe, Online"）——Avatar 根元素为 role="img"，会裁剪子元素语义，因此合成名称是辅助技术获知状态的途径。独立使用时状态点直接以 role="img" 暴露该标签。',
     },
     {
       name: 'icon',
@@ -80,7 +80,7 @@ export const docsDense = {
     variant:
       'colour + shape variant: success filled, neutral ring, error minus',
     label:
-      'accessible status label (not yet announced inside Avatar — role="img" prunes children)',
-    icon: 'icon centered in dot (hidden at tiny sizes); replaces the built-in shape glyph — differ it per status',
+      'accessible status label; composed into the Avatar accessible name ("Jane Doe, Online"); standalone dots expose role="img" with it directly',
+    icon: 'icon centered in dot (hidden at tiny sizes); replaces the built-in shape glyph, so differ it per status',
   },
 };

package/src/Avatar/AvatarStatusDot.tsx

@@ -115,10 +115,12 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
    * Describes the meaning of the indicator for screen readers
    * (e.g. "Online", "Accepted", "John Doe is busy").
    *
-   * Note: inside an Avatar the label is currently not announced — the
-   * Avatar root is `role="img"`, which prunes descendant semantics.
-   * Pass it anyway; composing status into the avatar's accessible name
-   * is a planned Avatar-level fix.
+   * Note: inside an Avatar the dot sits in the avatar's `role="img"`
+   * subtree, where descendant semantics are pruned — the dot is never its
+   * own stop there. Instead, Avatar reads this `label` and composes it into
+   * its own accessible name (e.g. "Jane Doe, Online"), which is how the
+   * status reaches assistive tech (WCAG 4.1.2). Standalone dots (outside an
+   * Avatar) expose `role="img"` with this label directly.
    */
   label?: string;
   /**

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -14,6 +14,7 @@ export const docs = {
       {guidance: true, description: 'Set max to limit visible avatars when the list is long; 3-5 is typical.'},
       {guidance: true, description: 'Use AvatarGroupOverflow for custom overflow content like a popover trigger or "add member" button.'},
       {guidance: true, description: 'Pass status dots, click handlers, or tooltips directly on each Avatar child.'},
+      {guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech.'},
       {guidance: false, description: "Don't nest AvatarGroups; use a single group with all avatars."},
     ],
     anatomy: [
@@ -94,6 +95,7 @@ export const docsDense = {
       {guidance: true, description: 'Set max to limit visible avatars (3-5 typical).'},
       {guidance: true, description: 'Use AvatarGroupOverflow for custom overflow (popover, add button).'},
       {guidance: true, description: 'Pass status dots / click handlers directly on each Avatar.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button.'},
       {guidance: false, description: "Don't nest AvatarGroups."},
     ],
   },