@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Avatar/Avatar.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Avatar',
@@ -32,6 +32,18 @@ export const docs = {
       {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.',
   props: [
@@ -64,7 +76,7 @@ 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: 'AvatarStatusDot',
@@ -79,16 +91,44 @@ export const docs = {
       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.",
+        "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'},
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -102,7 +142,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'person/team avatar w/ photo → initials → icon fallback chain',
   usage: {
@@ -112,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.'},
     ],
@@ -122,9 +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

@@ -2,7 +2,9 @@
 
 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" />,
@@ -221,3 +328,114 @@ describe('Avatar', () => {
     });
   });
 });
+
+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();
+  });
+});