@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

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,26 @@ 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']},
+    ],
+    vars: [
+      {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},
+      {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},
+      {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},
+      {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},
+    ],
+    derived: [
+      {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
+      {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
+      {property: 'color', vars: ['--_avatar-fallback-color']},
+      {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
     ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
@@ -62,16 +76,52 @@ export const docs = {
     {
       name: 'status',
       type: 'ReactNode',
-      description: 'Corner content for status indicators.',
+      description: 'Corner content for status indicators. A string `label` on the element (as on AvatarStatusDot) is composed into the avatar\'s accessible name (e.g. "Jane Doe, Online") so screen readers announce the status.',
       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',
+    },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When set, the avatar renders as an interactive link (`<a>` or a custom link component) pointing here. This follows the same element-swap rule as Button. Requires a meaningful accessible name via `alt` or `name`. Inside an AvatarGroup, interactive avatars share a single Tab stop and are reached with arrow keys.',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description:
+        'Custom link component used when `href` is set (e.g. Next.js `Link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description: 'Link target attribute. Only applies with `href`.',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description: 'Link rel attribute. Only applies with `href`.',
+    },
+    {
+      name: 'onClick',
+      type: '(e: MouseEvent) => void',
+      description:
+        'Click handler. When set without `href`, the avatar renders as a focusable `<button type="button">`. Requires a meaningful accessible name via `alt` or `name`.',
+    },
   ],
   components: [
     {name: 'AvatarStatusDot'},
@@ -102,6 +152,7 @@ export const docsDense = {
       {guidance: true, description: 'Always pass a name for initials fallback and screen reader alt text.'},
       {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
+      {guidance: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
       {guidance: false, description: 'Use for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],
@@ -112,7 +163,15 @@ export const docsDense = {
     name: 'user name for initials and alt text',
     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',
+    status:
+      'corner content for status indicators; its `label` is composed into the avatar accessible name ("Jane Doe, Online")',
+    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.",
+    href: 'renders avatar as a link (<a>/custom). Needs alt/name. Button-style element swap.',
+    as: 'custom link component for href (e.g. Next Link). Only with href.',
+    target: 'link target. Only with href.',
+    rel: 'link rel. Only with href.',
+    onClick: 'click handler → renders <button> when no href. Needs alt/name.',
   },
   components: [
     {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},

package/src/Avatar/Avatar.test.tsx

@@ -1,8 +1,10 @@
 // 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 userEvent from '@testing-library/user-event';
 import {Avatar} from './Avatar';
+import {AvatarStatusDot} from './AvatarStatusDot';
 
 describe('Avatar', () => {
   it('exposes role="img" with the name as accessible name', () => {
@@ -35,6 +37,19 @@ describe('Avatar', () => {
     expect(innerImg).toHaveAttribute('alt', '');
   });
 
+  it('renders fallback initials through the themeable font-size var, not a bare px literal', () => {
+    render(<Avatar name="Ada Lovelace" size="sm" data-testid="a" />);
+    const initials = screen.getByText('AL');
+    // The seam: the dynamic font size resolves to the Avatar-scoped var (with
+    // the proportional `size × 0.4` default baked in as the fallback), so a
+    // theme can re-scope it per size. A regression to a bare px literal would
+    // break theming.
+    const style = initials.getAttribute('style') ?? '';
+    expect(style).toContain('var(--_avatar-fallback-font-size,');
+    // Default still reproduces the proportional scale (sm = 24 × 0.4 = 9.6px).
+    expect(style).toMatch(/var\(--_avatar-fallback-font-size,\s*9\.6\d*px\)/);
+  });
+
   it('retries a new src after a previous src failed to load', () => {
     const {rerender} = render(
       <Avatar name="Ada" src="https://example.com/broken.jpg" />,
@@ -52,6 +67,98 @@ describe('Avatar', () => {
     expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
   });
 
+  describe('status in the accessible name (WCAG 4.1.2)', () => {
+    // The avatar root is role="img", which prunes descendant semantics —
+    // a label inside the status subtree is never announced on its own.
+    // Avatar composes the status element's `label` into its own name.
+    it('composes the status label into the accessible name for image avatars', () => {
+      render(
+        <Avatar
+          name="Ada Lovelace"
+          src="https://example.com/ada.jpg"
+          status={<AvatarStatusDot variant="success" label="Online" />}
+        />,
+      );
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace, Online'}),
+      ).toBeInTheDocument();
+    });
+
+    it('composes the status label into the accessible name for initials avatars', () => {
+      render(
+        <Avatar
+          name="Ada Lovelace"
+          status={<AvatarStatusDot variant="error" label="Busy" />}
+        />,
+      );
+      const avatar = screen.getByRole('img', {name: 'Ada Lovelace, Busy'});
+      expect(avatar).toBeInTheDocument();
+      expect(avatar).toHaveTextContent('AL');
+    });
+
+    it('composes the status label with alt when alt overrides name', () => {
+      render(
+        <Avatar
+          name="Ada"
+          alt="Ada Lovelace, profile photo"
+          status={<AvatarStatusDot label="Online" />}
+        />,
+      );
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace, profile photo, Online'}),
+      ).toBeInTheDocument();
+    });
+
+    it('keeps the plain name when there is no status', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" />);
+      expect(screen.getByTestId('a')).toHaveAttribute(
+        'aria-label',
+        'Ada Lovelace',
+      );
+    });
+
+    it('keeps the plain name when the status dot has no label', () => {
+      render(
+        <Avatar
+          name="Ada Lovelace"
+          data-testid="a"
+          status={<AvatarStatusDot variant="success" />}
+        />,
+      );
+      expect(screen.getByTestId('a')).toHaveAttribute(
+        'aria-label',
+        'Ada Lovelace',
+      );
+    });
+
+    it('keeps the plain name for custom status nodes without a label prop', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" status={<span />} />);
+      expect(screen.getByTestId('a')).toHaveAttribute(
+        'aria-label',
+        'Ada Lovelace',
+      );
+    });
+
+    it('announces a labelled status even on an otherwise decorative avatar', () => {
+      // A labelled status is meaningful information on its own — the avatar
+      // must not stay aria-hidden and swallow it.
+      render(
+        <Avatar data-testid="a" status={<AvatarStatusDot label="Online" />} />,
+      );
+      const el = screen.getByTestId('a');
+      expect(el).toHaveAttribute('role', 'img');
+      expect(el).toHaveAttribute('aria-label', 'Online');
+      expect(el).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('stays decorative with an unlabelled status and no name', () => {
+      render(<Avatar data-testid="a" status={<AvatarStatusDot />} />);
+      const el = screen.getByTestId('a');
+      expect(el).toHaveAttribute('aria-hidden', 'true');
+      expect(el).not.toHaveAttribute('aria-label');
+    });
+  });
+
   it('retries a new fallbackSrc after a previous fallbackSrc failed to load', () => {
     const {rerender} = render(
       <Avatar name="Ada" fallbackSrc="https://example.com/broken.jpg" />,
@@ -65,4 +172,270 @@ 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'));
+    });
+  });
+});
+
+describe('Avatar — interactivity (Button trichotomy)', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('renders a link when `href` is set (default LinkComponent is <a>)', () => {
+    render(<Avatar name="Ada Lovelace" href="/users/ada" />);
+    const link = screen.getByRole('link', {name: 'Ada Lovelace'});
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', '/users/ada');
+    // The static img semantics are gone — it's a control now.
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('forwards target/rel on the link', () => {
+    render(
+      <Avatar
+        name="Ada"
+        href="https://example.com"
+        target="_blank"
+        rel="noopener noreferrer"
+      />,
+    );
+    const link = screen.getByRole('link', {name: 'Ada'});
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('renders a <button type="button"> when `onClick` is set (no href)', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Avatar name="Ada" onClick={handleClick} />);
+    const button = screen.getByRole('button', {name: 'Ada'});
+    expect(button.tagName).toBe('BUTTON');
+    expect(button).toHaveAttribute('type', 'button');
+    await user.click(button);
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+
+  it('href wins over onClick (link, not button)', () => {
+    render(<Avatar name="Ada" href="/ada" onClick={() => {}} />);
+    expect(screen.getByRole('link', {name: 'Ada'})).toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+  });
+
+  it('stays a static element (no href, no onClick) — non-breaking default', () => {
+    render(<Avatar name="Ada" />);
+    expect(screen.getByRole('img', {name: 'Ada'})).toBeInTheDocument();
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+  });
+
+  it('stamps the data-avatar-item marker on the interactive link', () => {
+    render(<Avatar name="Ada" href="/ada" />);
+    expect(screen.getByRole('link', {name: 'Ada'})).toHaveAttribute(
+      'data-avatar-item',
+    );
+  });
+
+  it('stamps the data-avatar-item marker on the interactive button', () => {
+    render(<Avatar name="Ada" onClick={() => {}} />);
+    expect(screen.getByRole('button', {name: 'Ada'})).toHaveAttribute(
+      'data-avatar-item',
+    );
+  });
+
+  it('does not stamp data-avatar-item on a static avatar', () => {
+    render(<Avatar name="Ada" data-testid="a" />);
+    expect(screen.getByTestId('a')).not.toHaveAttribute('data-avatar-item');
+  });
+
+  it('carries a focus-visible ring class on the interactive element', () => {
+    // The interactive element applies the shared focus-visible accent ring via
+    // its StyleX class. We assert the element is focusable and receives focus.
+    render(<Avatar name="Ada" onClick={() => {}} />);
+    const button = screen.getByRole('button', {name: 'Ada'});
+    button.focus();
+    expect(button).toHaveFocus();
+    // className carries the avatar theming target so themes can style it.
+    expect(button.className).toContain('astryx-avatar');
+  });
+
+  it('warns in dev when interactive without an accessible name (href)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Avatar href="/somewhere" />);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('interactive avatar'),
+    );
+  });
+
+  it('warns in dev when interactive without an accessible name (onClick)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Avatar onClick={() => {}} />);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('interactive avatar'),
+    );
+  });
+
+  it('does not warn when interactive with a name', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Avatar name="Ada" href="/ada" />);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('does not warn for a static avatar without a name (decorative is fine)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Avatar data-testid="a" />);
+    expect(warn).not.toHaveBeenCalled();
+  });
 });