@astryxdesign/core 0.1.8 → 0.1.9-canary.75d2d03

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

package/src/Avatar/AvatarStatusDot.test.tsx

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {Avatar} from './Avatar';
+import {AvatarStatusDot, type AvatarStatusDotVariant} from './AvatarStatusDot';
+
+const GLYPH_SELECTOR = '.astryx-avatar-status-dot-glyph';
+const DOT_SELECTOR = '.astryx-avatar-status-dot';
+
+/**
+ * Renders an AvatarStatusDot inside an Avatar of the given numeric size and
+ * returns the dot root element. Size tiers: <=36 -> 10px dot (no icons),
+ * 40-72 -> 20px dot, >=96 -> 32px dot.
+ */
+function renderDot(
+  dotProps: React.ComponentProps<typeof AvatarStatusDot>,
+  avatarSize: 36 | 48 | 128 = 48,
+) {
+  const {container} = render(
+    <Avatar
+      name="Ada Lovelace"
+      size={avatarSize}
+      status={<AvatarStatusDot {...dotProps} />}
+    />,
+  );
+  const dot = container.querySelector(DOT_SELECTOR);
+  expect(dot).not.toBeNull();
+  return dot as HTMLElement;
+}
+
+describe('AvatarStatusDot', () => {
+  describe('shape glyphs (WCAG 1.4.1 — colour is not the only signal)', () => {
+    it('renders no glyph for success: the plain filled dot is the reference shape', () => {
+      const dot = renderDot({variant: 'success'});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+
+    it('renders a ring glyph for neutral', () => {
+      const dot = renderDot({variant: 'neutral'});
+      const glyph = dot.querySelector(GLYPH_SELECTOR);
+      expect(glyph).not.toBeNull();
+      expect(glyph).toHaveAttribute('data-shape', 'ring');
+    });
+
+    it('renders a minus glyph for error', () => {
+      const dot = renderDot({variant: 'error'});
+      const glyph = dot.querySelector(GLYPH_SELECTOR);
+      expect(glyph).not.toBeNull();
+      expect(glyph).toHaveAttribute('data-shape', 'minus');
+    });
+
+    it('hides the glyph from assistive tech: it is a visual redundancy of the status', () => {
+      const dot = renderDot({variant: 'error'});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it('renders glyphs at every size tier', () => {
+      for (const size of [36, 48, 128] as const) {
+        const dot = renderDot({variant: 'neutral'}, size);
+        expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+      }
+    });
+
+    it('draws the glyph as an inline svg sized to the dot inner field', () => {
+      // The glyph is a stroked <svg>, matching how the rest of the system
+      // draws marks (Icon's defaultIcons, the CheckboxInput checkmark).
+      // Its viewBox is 1 user unit per px of the dot's inner field
+      // (dot minus both borders), so stroke widths below are literal px.
+      const cases = [
+        [36, 8],
+        [48, 16],
+        [128, 24],
+      ] as const;
+      for (const [avatarSize, field] of cases) {
+        const glyph = renderDot({variant: 'neutral'}, avatarSize).querySelector(
+          GLYPH_SELECTOR,
+        ) as SVGElement;
+        expect(glyph.tagName.toLowerCase(), `avatar ${avatarSize}`).toBe('svg');
+        expect(glyph.getAttribute('viewBox'), `avatar ${avatarSize}`).toBe(
+          `0 0 ${field} ${field}`,
+        );
+        expect(glyph.getAttribute('width'), `avatar ${avatarSize}`).toBe(
+          String(field),
+        );
+        expect(glyph.getAttribute('height'), `avatar ${avatarSize}`).toBe(
+          String(field),
+        );
+      }
+    });
+
+    it('strokes the ring at the system glyph weight, not a quarter of the field', () => {
+      // stroke ~= field / 12, floored at 1px for the smallest tier, which
+      // puts these on the icon family's 1 / 1.5 / 2 ladder (~6-12% of the
+      // field) instead of the 25% band a CSS box cutout produced.
+      const cases = [
+        // avatar size, field, stroke, radius = (field - stroke) / 2
+        [36, 8, 1, 3.5],
+        [48, 16, 1.5, 7.25],
+        [128, 24, 2, 11],
+      ] as const;
+      for (const [avatarSize, field, stroke, radius] of cases) {
+        const circle = renderDot(
+          {variant: 'neutral'},
+          avatarSize,
+        ).querySelector(`${GLYPH_SELECTOR} circle`) as SVGCircleElement;
+        expect(circle, `avatar ${avatarSize}`).not.toBeNull();
+        expect(
+          circle.getAttribute('stroke-width'),
+          `avatar ${avatarSize}`,
+        ).toBe(String(stroke));
+        // Radius is to the stroke centreline, so the ring's outer edge lands
+        // exactly on the inner field and never clips against the border.
+        expect(circle.getAttribute('r'), `avatar ${avatarSize}`).toBe(
+          String(radius),
+        );
+        expect(circle.getAttribute('cx'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(circle.getAttribute('cy'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(circle.getAttribute('fill'), `avatar ${avatarSize}`).toBe(
+          'none',
+        );
+      }
+    });
+
+    it('strokes the minus bar at the same weight, spanning 75% of the field with round caps', () => {
+      // Ends are inset by half the stroke so the round caps land inside the
+      // 75% span rather than overhanging it.
+      const cases = [
+        // avatar size, field, stroke, x1, x2
+        [36, 8, 1, 1.5, 6.5],
+        [48, 16, 1.5, 2.75, 13.25],
+        [128, 24, 2, 4, 20],
+      ] as const;
+      for (const [avatarSize, field, stroke, x1, x2] of cases) {
+        const line = renderDot({variant: 'error'}, avatarSize).querySelector(
+          `${GLYPH_SELECTOR} line`,
+        ) as SVGLineElement;
+        expect(line, `avatar ${avatarSize}`).not.toBeNull();
+        expect(line.getAttribute('stroke-width'), `avatar ${avatarSize}`).toBe(
+          String(stroke),
+        );
+        expect(line.getAttribute('x1'), `avatar ${avatarSize}`).toBe(
+          String(x1),
+        );
+        expect(line.getAttribute('x2'), `avatar ${avatarSize}`).toBe(
+          String(x2),
+        );
+        expect(line.getAttribute('y1'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(line.getAttribute('y2'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(
+          line.getAttribute('stroke-linecap'),
+          `avatar ${avatarSize}`,
+        ).toBe('round');
+      }
+    });
+
+    it('paints both glyphs from currentColor so the dot owns the ink colour', () => {
+      for (const variant of ['neutral', 'error'] as const) {
+        const mark = renderDot({variant}, 48).querySelector(
+          `${GLYPH_SELECTOR} circle, ${GLYPH_SELECTOR} line`,
+        ) as SVGElement;
+        expect(mark.getAttribute('stroke'), variant).toBe('currentColor');
+      }
+    });
+
+    it('fills the ring variant with surface and inks it with the variant colour', () => {
+      // A ring only reads as hollow if its interior is not the variant
+      // colour, so `neutral` inverts: surface fill, coloured stroke.
+      // StyleX atomic classes are deterministic, so a local probe pins it.
+      const probe = stylex.create({
+        ring: {
+          backgroundColor: colorVars['--color-background-surface'],
+          color: colorVars['--color-text-secondary'],
+        },
+      });
+      const dot = renderDot({variant: 'neutral'}, 48);
+      const atomicClasses = (stylex.props(probe.ring).className ?? '')
+        .split(' ')
+        // Dev mode prepends a per-file `File__style.key` debug class that
+        // legitimately differs between the probe and the component.
+        .filter(cls => !cls.includes('__'));
+      expect(atomicClasses.length).toBeGreaterThan(0);
+      for (const cls of atomicClasses) {
+        expect(dot.className).toContain(cls);
+      }
+    });
+
+    it('lets a user icon inherit the dot ink instead of hard-coding surface', () => {
+      // Surface ink on the surface-filled ring variant would be invisible.
+      const probe = stylex.create({
+        surfaceInk: {color: colorVars['--color-background-surface']},
+      });
+      renderDot(
+        {variant: 'neutral', icon: <svg data-testid="user-icon" />},
+        48,
+      );
+      const iconWrapper = screen.getByTestId('user-icon')
+        .parentElement as HTMLElement;
+      const surfaceInkClasses = (stylex.props(probe.surfaceInk).className ?? '')
+        .split(' ')
+        .filter(cls => !cls.includes('__'));
+      expect(surfaceInkClasses.length).toBeGreaterThan(0);
+      for (const cls of surfaceInkClasses) {
+        expect(iconWrapper.className).not.toContain(cls);
+      }
+    });
+
+    it('renders no glyph for custom augmented variants (documented: they must bring their own non-colour mark)', () => {
+      const dot = renderDot({variant: 'away' as AvatarStatusDotVariant});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+  });
+
+  describe('glyph and icon interplay', () => {
+    it('suppresses the glyph when a user icon renders: the icon is the non-colour mark', () => {
+      const dot = renderDot(
+        {variant: 'error', icon: <svg data-testid="user-icon" />},
+        48,
+      );
+      expect(screen.getByTestId('user-icon')).toBeInTheDocument();
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+
+    it('keeps the glyph at the smallest tier where icons never render', () => {
+      const dot = renderDot(
+        {variant: 'error', icon: <svg data-testid="user-icon" />},
+        36,
+      );
+      expect(screen.queryByTestId('user-icon')).not.toBeInTheDocument();
+      expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+    });
+
+    it('keeps the glyph for non-renderable icons: booleans from `cond && <Icon />` render nothing', () => {
+      for (const nonRenderable of [true, false, ''] as const) {
+        const dot = renderDot({variant: 'error', icon: nonRenderable}, 48);
+        expect(
+          dot.querySelector(GLYPH_SELECTOR),
+          `icon={${JSON.stringify(nonRenderable)}}`,
+        ).not.toBeNull();
+      }
+    });
+  });
+
+  describe('existing contract', () => {
+    it('exposes role="img" with the label as accessible name when label is provided', () => {
+      const dot = renderDot({variant: 'success', label: 'Online'});
+      expect(dot).toHaveAttribute('role', 'img');
+      expect(dot).toHaveAttribute('aria-label', 'Online');
+    });
+
+    it('has no img role without a label', () => {
+      const dot = renderDot({variant: 'success'});
+      expect(dot).not.toHaveAttribute('role');
+    });
+
+    it('reflects the variant as a data attribute for theming', () => {
+      const dot = renderDot({variant: 'neutral'});
+      expect(dot).toHaveAttribute('data-variant', 'neutral');
+    });
+
+    it('renders the user icon at tiers with room for it, hidden from assistive tech', () => {
+      renderDot(
+        {variant: 'success', icon: <svg data-testid="user-icon" />},
+        128,
+      );
+      const icon = screen.getByTestId('user-icon');
+      expect(icon).toBeInTheDocument();
+      expect(icon.parentElement).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+});