@astryxdesign/core 0.1.8 → 0.1.9

package/src/AppShell/AppShell.tsx

@@ -24,6 +24,7 @@ import {
   isValidElement,
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -600,10 +601,14 @@ export function AppShell({
   // =========================================================================
   // Mobile context — shared with MobileNavToggle and future TopNav mobile
   // =========================================================================
+  // Stable id shared by the drawer (applied as its `id`) and the toggle
+  // (referenced via `aria-controls`) so screen readers know what it controls.
+  const mobileNavId = useId();
   const mobileContextValue = useMemo<AppShellMobileContextValue>(
     () => ({
       isMobile: isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       toggleMobileNav: () =>
         mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
       openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
@@ -614,6 +619,7 @@ export function AppShell({
     [
       isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       setMobileNavOpen,
       mobileNavEnabled,
       mobileNavHasToggle,

package/src/AppShell/AppShellMobileContext.tsx

@@ -20,6 +20,14 @@ export interface AppShellMobileContextValue {
   isMobile: boolean;
   /** Whether the mobile nav drawer is currently open */
   isMobileNavOpen: boolean;
+  /**
+   * DOM id of the mobile nav drawer. `AppShell` sets this so the toggle can
+   * point its `aria-controls` at the drawer and the drawer can apply it as its
+   * `id`. Optional: callers that construct this context by hand may omit it, in
+   * which case `MobileNav` falls back to a locally generated id and the toggle
+   * simply drops `aria-controls`.
+   */
+  mobileNavId?: string;
   /** Toggle the mobile nav drawer open/closed */
   toggleMobileNav: () => void;
   /** Open the mobile nav drawer */

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -31,6 +31,12 @@ export const docs = {
       description:
         'Whether the AppShell-managed mobile navigation drawer is open.',
     },
+    {
+      name: 'mobileNavId',
+      type: 'string | undefined',
+      description:
+        'DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer.',
+    },
     {
       name: 'toggleMobileNav',
       type: '() => void',
@@ -111,6 +117,8 @@ export const docsDense = {
     isMobile:
       'viewport below AppShell mobile nav breakpoint? Use to sync AppShell-adjacent mobile UI',
     isMobileNavOpen: 'AppShell-managed mobile nav drawer open?',
+    mobileNavId:
+      'DOM id of the drawer; point custom toggle aria-controls at it',
     toggleMobileNav: 'toggle drawer; no-op when mobile nav disabled',
     openMobileNav: 'open drawer; no-op when mobile nav disabled',
     closeMobileNav: 'close drawer',

package/src/Avatar/Avatar.doc.mjs

@@ -15,6 +15,7 @@ export const docs = {
       {guidance: true, description: 'Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.'},
       {guidance: true, description: 'Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.'},
       {guidance: true, description: 'Add a status dot when knowing someone\'s availability matters, like in chat or team views.'},
+      {guidance: true, description: 'When wrapping an Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
       {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular to stay consistent across the system.'},
     ],
@@ -22,13 +23,14 @@ export const docs = {
       {name: 'Photo', required: false, description: 'The profile image, loaded from the src URL. Shown when available.'},
       {name: 'Initials', required: false, description: 'One or two letters extracted from the name. Shown when no photo is available.'},
       {name: 'Default icon', required: false, description: 'A generic person silhouette. Shown when there is no photo or name.'},
-      {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy).'},
+      {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy). Each variant pairs colour with a distinct shape so status does not rely on colour alone.'},
     ],
   },
   theming: {
     targets: [
       {className: 'astryx-avatar', visualProps: ['size']},
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
+      {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
@@ -65,13 +67,21 @@ export const docs = {
       description: 'Corner content for status indicators.',
       slotElements: [
         {
-          __element: 'StatusDot',
+          __element: 'AvatarStatusDot',
           props: {
-            variant: 'online',
+            variant: 'success',
+            label: 'Online',
           },
         },
       ],
     },
+    {
+      name: 'tooltip',
+      type: 'string | boolean',
+      description:
+        "Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard — set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name.",
+      default: 'true',
+    },
   ],
   components: [
     {name: 'AvatarStatusDot'},
@@ -113,6 +123,8 @@ export const docsDense = {
     alt: 'alt text; falls back to name',
     size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
     status: 'corner content for status indicators',
+    tooltip:
+      "hover/focus tooltip. true/omitted → name; string → that text; false → none. Owns its tooltip; set false when wrapping in your own Tooltip/HoverCard. Default true.",
   },
   components: [
     {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},

package/src/Avatar/Avatar.test.tsx

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {Avatar} from './Avatar';
 
@@ -65,4 +65,159 @@ describe('Avatar', () => {
     expect(img).not.toBeNull();
     expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
   });
+
+  // --- Name tooltip (tooltip?: string | boolean) ---
+  describe('name tooltip', () => {
+    const originalShowPopover = HTMLElement.prototype.showPopover;
+    const originalHidePopover = HTMLElement.prototype.hidePopover;
+
+    beforeEach(() => {
+      // jsdom does not implement the Popover API the tooltip layer uses.
+      HTMLElement.prototype.showPopover = vi.fn();
+      HTMLElement.prototype.hidePopover = vi.fn();
+    });
+
+    afterEach(() => {
+      HTMLElement.prototype.showPopover = originalShowPopover;
+      HTMLElement.prototype.hidePopover = originalHidePopover;
+    });
+
+    it('shows the name in a tooltip by default', () => {
+      render(<Avatar name="Ada Lovelace" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Ada Lovelace');
+    });
+
+    it('shows a custom string tooltip instead of the name', () => {
+      render(<Avatar name="alovelace" tooltip="Ada Lovelace, Mathematician" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Ada Lovelace, Mathematician');
+      expect(tooltip).not.toHaveTextContent('alovelace');
+    });
+
+    it('renders no tooltip when tooltip={false}', () => {
+      render(<Avatar name="Ada Lovelace" tooltip={false} />);
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+    });
+
+    it('renders no tooltip for a decorative avatar (no name/alt)', () => {
+      render(<Avatar src="https://example.com/x.jpg" />);
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+    });
+
+    it('renders no tooltip when tooltip is true/default but name is empty', () => {
+      render(<Avatar name="   " alt="Profile photo" data-testid="a" />);
+      // A whitespace-only name yields nothing to show, and the default tooltip
+      // uses `name` (not `alt`), so there is no tooltip.
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+      // The accessible name still comes from alt, unaffected.
+      expect(
+        screen.getByRole('img', {name: 'Profile photo'}),
+      ).toBeInTheDocument();
+    });
+
+    it('still shows a custom string tooltip when there is no name', () => {
+      render(<Avatar tooltip="Anonymous user" data-testid="a" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Anonymous user');
+    });
+
+    it('makes the root focusable while a tooltip is attached', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" />);
+      expect(screen.getByTestId('a')).toHaveAttribute('tabindex', '0');
+    });
+
+    it('does not add a tab stop when the tooltip is disabled', () => {
+      render(<Avatar name="Ada Lovelace" tooltip={false} data-testid="a" />);
+      expect(screen.getByTestId('a')).not.toHaveAttribute('tabindex');
+    });
+
+    it('keeps the accessible name on the root regardless of the tooltip', () => {
+      const {rerender} = render(<Avatar name="Ada Lovelace" />);
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace'}),
+      ).toBeInTheDocument();
+
+      rerender(<Avatar name="Ada Lovelace" tooltip={false} />);
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace'}),
+      ).toBeInTheDocument();
+
+      rerender(<Avatar name="alovelace" tooltip="Ada Lovelace, Eng" />);
+      // alt||name still drives the accessible name — not the custom tooltip.
+      expect(screen.getByRole('img', {name: 'alovelace'})).toBeInTheDocument();
+
+      rerender(<Avatar name="alovelace" alt="Ada's profile photo" />);
+      expect(
+        screen.getByRole('img', {name: "Ada's profile photo"}),
+      ).toBeInTheDocument();
+    });
+
+    it('does not describe the root with the default name tooltip (no double-announce)', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" />);
+      // The default name tooltip is visual-only: its text duplicates the root
+      // aria-label, so we deliberately do NOT wire aria-describedby (OQ-4).
+      expect(screen.getByTestId('a')).not.toHaveAttribute('aria-describedby');
+    });
+
+    it('describes the root with a custom string tooltip (matches Button)', () => {
+      render(
+        <Avatar
+          name="alovelace"
+          tooltip="Ada Lovelace, Mathematician"
+          data-testid="a"
+        />,
+      );
+      const root = screen.getByTestId('a');
+      const describedBy = root.getAttribute('aria-describedby');
+      expect(describedBy).toBeTruthy();
+      // aria-describedby points at the rendered tooltip layer.
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip.id).toBeTruthy();
+      expect(describedBy).toContain(tooltip.id);
+    });
+
+    it('composes a consumer aria-describedby with the custom tooltip description', () => {
+      render(
+        <>
+          <span id="extra-desc">extra description</span>
+          <Avatar
+            name="alovelace"
+            tooltip="Ada Lovelace, Eng"
+            aria-describedby="extra-desc"
+            data-testid="a"
+          />
+        </>,
+      );
+      const describedBy = screen
+        .getByTestId('a')
+        .getAttribute('aria-describedby');
+      expect(describedBy).toContain('extra-desc');
+    });
+
+    it('preserves a consumer aria-describedby with the default name tooltip', () => {
+      render(
+        <>
+          <span id="extra-desc">extra description</span>
+          <Avatar
+            name="Ada Lovelace"
+            aria-describedby="extra-desc"
+            data-testid="a"
+          />
+        </>,
+      );
+      // Default name tooltip does not touch aria-describedby, so the consumer
+      // value passes through untouched.
+      expect(screen.getByTestId('a')).toHaveAttribute(
+        'aria-describedby',
+        'extra-desc',
+      );
+    });
+
+    it('forwards the consumer ref to the root while a tooltip is attached', () => {
+      const ref = {current: null as HTMLDivElement | null};
+      render(<Avatar name="Ada Lovelace" ref={ref} data-testid="a" />);
+      expect(ref.current).toBe(screen.getByTestId('a'));
+    });
+  });
 });

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
  *
@@ -26,8 +27,9 @@ 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';
 
 /**
  * The offset ratio for positioning elements on a circle's edge at 45°.
@@ -133,6 +135,19 @@ 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.
+  focusable: {
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
+  },
 });
 
 /**
@@ -216,6 +231,19 @@ 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;
 }
 
 /**
@@ -265,6 +293,8 @@ 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} />
  * ```
  */
 export function Avatar({
@@ -275,6 +305,7 @@ export function Avatar({
   size = 'md',
   src,
   status,
+  tooltip = true,
   xstyle,
   className,
   style,
@@ -303,19 +334,66 @@ export function Avatar({
   const resolvedSize = avatarGroup?.size ?? size;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
 
-  return (
+  // 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 made focusable (below).
+  const tooltipHook = useTooltip({
+    placement: 'above',
+    isEnabled: showTooltip,
+  });
+  const rootRef = mergeRefs(ref, showTooltip ? tooltipHook.ref : undefined);
+  const describedByProp =
+    showTooltip && isCustomTooltip
+      ? {
+          'aria-describedby':
+            [props['aria-describedby'], tooltipHook.describedBy]
+              .filter(Boolean)
+              .join(' ') || undefined,
+        }
+      : null;
+
+  const avatarElement = (
     <AvatarSizeContext value={numericSize}>
       <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. Only while active.
+        tabIndex={showTooltip ? 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),
@@ -368,6 +446,20 @@ export function Avatar({
       </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.
+  return (
+    <>
+      {avatarElement}
+      {tooltipHook.renderTooltip(trimmedTooltip)}
+    </>
+  );
 }
 
 Avatar.displayName = 'Avatar';

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