@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/Avatar/Avatar.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState
+ * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ *   (Tooltip hook) for the optional name-on-hover tooltip
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
  *
@@ -13,6 +14,8 @@
  * - /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';
@@ -26,8 +29,11 @@ import {
 } from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
-import {mergeProps} from '../utils';
+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';
 
 /**
  * The offset ratio for positioning elements on a circle's edge at 45°.
@@ -59,7 +65,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';
 
@@ -104,6 +110,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',
@@ -124,15 +135,65 @@ 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: {
     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.
+  focusable: {
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':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,
+    },
+  },
 });
 
 /**
@@ -143,8 +204,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,
@@ -216,6 +282,48 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    * Typically used for status indicators or badges.
    */
   status?: ReactNode;
+  /**
+   * Tooltip shown on hover (and keyboard focus).
+   * - omitted / `true`: show the avatar's `name`
+   * - a string: show that text instead
+   * - `false`: no tooltip
+   *
+   * The avatar owns this tooltip. It is NOT auto-disabled when wrapped in your
+   * own Tooltip/HoverCard — set `tooltip={false}` if you provide your own
+   * overlay. No tooltip is shown if `tooltip` is `true`/omitted and there is
+   * no (non-whitespace) `name`.
+   * @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>;
 }
 
 /**
@@ -265,6 +373,10 @@ function DefaultIcon({size}: {size: number}) {
  * <Avatar src="/user.jpg" name="John Doe" />
  * <Avatar name="Jane Smith" size="xl" />
  * <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({
@@ -275,6 +387,12 @@ export function Avatar({
   size = 'md',
   src,
   status,
+  tooltip = true,
+  href,
+  as,
+  target,
+  rel,
+  onClick,
   xstyle,
   className,
   style,
@@ -303,70 +421,212 @@ export function Avatar({
   const resolvedSize = avatarGroup?.size ?? size;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
 
-  return (
-    <AvatarSizeContext value={numericSize}>
+  // Resolve the tooltip content:
+  // - `false`            → no tooltip
+  // - a string           → that string
+  // - `true` / omitted   → the `name` (a whitespace-only name yields nothing)
+  // Note: the *visible* tooltip prefers `name` (not `alt`); the *accessible
+  // name* on the root still uses `alt || name` above, independent of this.
+  const tooltipContent =
+    tooltip === false
+      ? undefined
+      : typeof tooltip === 'string'
+        ? tooltip
+        : name;
+  const trimmedTooltip = tooltipContent?.trim();
+  const showTooltip = trimmedTooltip != null && trimmedTooltip !== '';
+  // Whether the tooltip text is a consumer-authored override (a custom string)
+  // rather than the default name. A custom description is worth wiring to
+  // `aria-describedby` (it adds information, matching Button); the default name
+  // tooltip is visual-only — its text duplicates the root `aria-label`, so
+  // describing it too would double-announce the same name (OQ-4).
+  const isCustomTooltip = typeof tooltip === 'string';
+
+  // Own the name tooltip via the Tooltip hook (the Button pattern), which
+  // 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 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
+      ? {
+          'aria-describedby':
+            [props['aria-describedby'], tooltipHook.describedBy]
+              .filter(Boolean)
+              .join(' ') || undefined,
+        }
+      : null;
+
+  // 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={ref}
+        ref={rootRef}
         role={isDecorative ? 'presentation' : 'img'}
         aria-label={isDecorative ? undefined : accessibleName}
         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. Suppressed inside
+        // an AvatarGroup, which owns a single roving tab stop for its members.
+        tabIndex={showTooltip && !avatarGroup ? 0 : undefined}
         data-testid={testId}
-        {...mergeProps(
-          themeProps('avatar', {size: resolvedSize}),
-          stylex.props(
-            styles.wrapper,
-            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>
-        )}
+        {...describedByProp}
+        {...rootStylexProps}>
+        {visualContent}
       </div>
-    </AvatarSizeContext>
+    );
+  }
+
+  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}
+      {showTooltip ? tooltipHook.renderTooltip(trimmedTooltip) : null}
+    </>
   );
 }
 

package/src/Avatar/AvatarStatusDot.doc.mjs

@@ -7,23 +7,27 @@ export const docs = {
   subComponentOf: 'Avatar',
   displayName: 'Avatar Status Dot',
   isHiddenFromOverview: true,
-  description: 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',
+  description:
+    'Size-aware status indicator dot that reads avatar size from context and scales proportionally. Each variant pairs a colour with a distinct built-in shape (filled, ring, minus) so status is never conveyed by colour alone (WCAG 1.4.1).',
   props: [
     {
       name: 'variant',
       type: "'success' | 'neutral' | 'error'",
-      description: 'Semantic color variant of the dot.',
+      description:
+        'Semantic variant pairing colour with a distinct shape: success = filled green dot, neutral = grey ring, error = red dot with a minus bar.',
       default: "'success'",
     },
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for screen readers.',
+      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.',
     },
     {
       name: 'icon',
       type: 'ReactNode',
-      description: 'Icon centered inside the dot (hidden at tiny sizes).',
+      description:
+        'Icon centered inside the dot (hidden at tiny sizes). A rendered icon replaces the built-in shape glyph, so use a different icon per status.',
       slotElements: [
         {
           __element: 'Icon',
@@ -41,23 +45,27 @@ export const docsZh = {
   name: 'AvatarStatusDot',
   isHiddenFromOverview: true,
   displayName: 'Avatar Status Dot',
-  description: '尺寸感知的状态指示点，从上下文中读取头像尺寸并等比缩放。',
+  description:
+    '尺寸感知的状态指示点，从上下文中读取头像尺寸并等比缩放。每个变体将颜色与独特形状（实心、圆环、横杠）配对，确保状态不仅靠颜色传达（WCAG 1.4.1）。',
   props: [
     {
       name: 'variant',
       type: "'success' | 'neutral' | 'error'",
-      description: '状态点的语义颜色变体。',
+      description:
+        '语义变体，颜色与形状配对：success = 绿色实心点，neutral = 灰色圆环，error = 带横杠的红色点。',
       default: "'success'",
     },
     {
       name: 'label',
       type: 'string',
-      description: '屏幕阅读器的无障碍标签。',
+      description:
+        '描述状态的无障碍标签。目前在 Avatar 内不会被朗读（Avatar 根元素为 role="img"，会裁剪子元素语义）——仍请传入；Avatar 层面的名称合成修复已在计划中。',
     },
     {
       name: 'icon',
       type: 'ReactNode',
-      description: '居中显示在状态点内的图标（tiny 尺寸时隐藏）。',
+      description:
+        '居中显示在状态点内的图标（tiny 尺寸时隐藏）。渲染的图标会替换内置形状标记，请为每个状态使用不同的图标。',
     },
   ],
 };
@@ -66,10 +74,13 @@ export const docsDense = {
   name: 'AvatarStatusDot',
   isHiddenFromOverview: true,
   displayName: 'Avatar Status Dot',
-  description: 'size-aware status dot, reads avatar size from context + scales proportionally',
+  description:
+    'size-aware status dot, reads avatar size from context + scales proportionally; variants pair colour with shape (filled/ring/minus) per WCAG 1.4.1',
   propDescriptions: {
-    variant: 'semantic color variant',
-    label: 'accessible label for screen readers',
-    icon: 'icon centered in dot (hidden at tiny sizes)',
+    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',
   },
 };