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

package/dist/Avatar/Avatar.d.ts

@@ -10,9 +10,12 @@
  * - /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 { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
+import type { LinkComponentType } from '../Link/types';
 /**
  * Named size options.
  *
@@ -84,6 +87,35 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
      * @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>;
 }
 /**
  * Avatar component for displaying user profile pictures.
@@ -98,9 +130,11 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
  * <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 declare function Avatar({ alt, 'data-testid': testId, fallbackSrc, name, size, src, status, tooltip, xstyle, className, style, ref, ...props }: AvatarProps): import("react").JSX.Element;
+export declare function Avatar({ alt, 'data-testid': testId, fallbackSrc, name, size, src, status, tooltip, href, as, target, rel, onClick, xstyle, className, style, ref, ...props }: AvatarProps): import("react").JSX.Element;
 export declare namespace Avatar {
     var displayName: string;
 }

package/dist/Avatar/Avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAuC5C;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAkGD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAsCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAW,EACX,GAAG,EACH,MAAM,EACN,OAAc,EACd,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAqJb;yBAnKe,MAAM"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAc5C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AA2BrD;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAmID,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;CAChD;AAsCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAW,EACX,GAAG,EACH,MAAM,EACN,OAAc,EACd,IAAI,EACJ,EAAE,EACF,MAAM,EACN,GAAG,EACH,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAyOb;yBA5Pe,MAAM"}

package/dist/Avatar/Avatar.js

@@ -14,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 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -24,7 +26,8 @@ import { useAvatarGroup } from "../AvatarGroup/AvatarGroupContext.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTooltip } from "../Tooltip/useTooltip.js";
-
+import { useLinkComponent } from "../Link/useLinkComponent.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
  * The offset ratio for positioning elements on a circle's edge at 45°.
  *
@@ -37,7 +40,6 @@ import { useTooltip } from "../Tooltip/useTooltip.js";
  *
  * This constant represents that ratio: (1 - 1/√2) / 2 ≈ 0.146
  */
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 
 /**
@@ -129,6 +131,24 @@ const styles = {
     kI3sdo: "x17nn4n9",
     kInvED: "x1wfwxd8 x7s97pk",
     $$css: true
+  },
+  interactive: {
+    kysU6D: "xjyslct",
+    kmVPX3: "x1717udv",
+    kogj98: "x1ghz6dp",
+    kMzoRj: "xc342km",
+    ksu8eU: "xng3xce",
+    kWkggS: "xjbqb8w",
+    kMwMTN: "x1heor9g",
+    kVVagm: "xln7xf2",
+    kybGjl: "x1hl2dhg",
+    kkrTdU: "x1ypdohk",
+    kaIpWk: "xjspbzw",
+    kMeerF: "x1k57tk5 x784prv",
+    k3XXqK: "x1t137rt x9v5kkp",
+    kjBf7l: "xzunyri",
+    kInvED: "x1wfwxd8 x7s97pk",
+    $$css: true
   }
 };
 
@@ -238,6 +258,8 @@ function DefaultIcon({
  * <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({
@@ -249,6 +271,11 @@ export function Avatar({
   src,
   status,
   tooltip = true,
+  href,
+  as,
+  target,
+  rel,
+  onClick,
   xstyle,
   className,
   style,
@@ -293,18 +320,117 @@ export function Avatar({
   // 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).
+  // 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;
-  const avatarElement = /*#__PURE__*/_jsx(AvatarSizeContext, {
-    value: numericSize,
-    children: /*#__PURE__*/_jsxs("div", {
+
+  // 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 = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsxs("div", {
+      ...stylex.props(styles.content, dynamicStyles.size(numericSize)),
+      children: [showImage && /*#__PURE__*/_jsx("img", {
+        src: src,
+        alt: "",
+        onError: () => setErroredSrc(src),
+        ...{
+          className: "xh8yej3 x5yr21d xl1xv1r"
+        }
+      }), showFallbackImage && /*#__PURE__*/_jsx("img", {
+        src: fallbackSrc,
+        alt: "",
+        onError: () => setErroredFallbackSrc(fallbackSrc),
+        ...{
+          className: "xh8yej3 x5yr21d xl1xv1r"
+        }
+      }), showInitials && /*#__PURE__*/_jsx("div", {
+        ...stylex.props(styles.fallback, dynamicStyles.fontSize(numericSize)),
+        children: getInitials(name)
+      }), showIcon && /*#__PURE__*/_jsx("div", {
+        ...{
+          className: "x78zum5 x6s0dn4 xl56j7k xh8yej3 x5yr21d x17x4s8c xv1l7n4 x9ynric x1e4wzip xtvhhri"
+        },
+        children: /*#__PURE__*/_jsx(DefaultIcon, {
+          size: numericSize
+        })
+      })]
+    }), status && /*#__PURE__*/_jsx("div", {
+      ...stylex.props(styles.status, dynamicStyles.statusPosition(numericSize)),
+      children: status
+    })]
+  });
+
+  // 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;
+
+  // `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;
+  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 = /*#__PURE__*/_jsx(LinkComponent, {
+      ...interactivePassthrough,
+      ...describedByProp,
+      ref: rootRef,
+      href: href,
+      target: target,
+      rel: rel,
+      "aria-label": accessibleName,
+      "data-avatar-item": "",
+      "data-testid": testId,
+      onClick: onClick,
+      ...rootStylexProps,
+      children: visualContent
+    });
+  } else if (renderAsButton) {
+    rootElement = /*#__PURE__*/_jsx("button", {
+      ...interactivePassthrough,
+      ...describedByProp,
+      ref: rootRef,
+      type: "button",
+      "aria-label": accessibleName,
+      "data-avatar-item": "",
+      "data-testid": testId,
+      onClick: onClick,
+      ...rootStylexProps,
+      children: visualContent
+    });
+  } else {
+    rootElement = /*#__PURE__*/_jsx("div", {
       ...props,
       ref: rootRef,
       role: isDecorative ? 'presentation' : 'img',
@@ -312,46 +438,19 @@ export function Avatar({
       "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.
+      // (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 ? 0 : undefined,
+      tabIndex: showTooltip && !avatarGroup ? 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), xstyle), className, style),
-      children: [/*#__PURE__*/_jsxs("div", {
-        ...stylex.props(styles.content, dynamicStyles.size(numericSize)),
-        children: [showImage && /*#__PURE__*/_jsx("img", {
-          src: src,
-          alt: "",
-          onError: () => setErroredSrc(src),
-          ...{
-            className: "xh8yej3 x5yr21d xl1xv1r"
-          }
-        }), showFallbackImage && /*#__PURE__*/_jsx("img", {
-          src: fallbackSrc,
-          alt: "",
-          onError: () => setErroredFallbackSrc(fallbackSrc),
-          ...{
-            className: "xh8yej3 x5yr21d xl1xv1r"
-          }
-        }), showInitials && /*#__PURE__*/_jsx("div", {
-          ...stylex.props(styles.fallback, dynamicStyles.fontSize(numericSize)),
-          children: getInitials(name)
-        }), showIcon && /*#__PURE__*/_jsx("div", {
-          ...{
-            className: "x78zum5 x6s0dn4 xl56j7k xh8yej3 x5yr21d x17x4s8c xv1l7n4 x9ynric x1e4wzip xtvhhri"
-          },
-          children: /*#__PURE__*/_jsx(DefaultIcon, {
-            size: numericSize
-          })
-        })]
-      }), status && /*#__PURE__*/_jsx("div", {
-        ...stylex.props(styles.status, dynamicStyles.statusPosition(numericSize)),
-        children: status
-      })]
-    })
+      ...rootStylexProps,
+      children: visualContent
+    });
+  }
+  const avatarElement = /*#__PURE__*/_jsx(AvatarSizeContext, {
+    value: numericSize,
+    children: rootElement
   });
   if (!showTooltip) {
     return avatarElement;

package/dist/AvatarGroup/AvatarGroup.d.ts

@@ -8,6 +8,12 @@
  * one AvatarGroupOverflow). The group provides overlap styling via
  * context — no child introspection needed.
  *
+ * When the group contains interactive avatars (rendered as links/buttons) or an
+ * interactive AvatarGroupOverflow, it becomes a single Tab stop with roving
+ * arrow-key focus (via useListFocus with hasRovingTabIndex) and exposes a
+ * screen-reader keyboard hint via aria-describedby. A purely static facepile
+ * gets neither — it stays a plain non-focusable group.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AvatarGroup/AvatarGroup.doc.mjs (props table, features)
  * - /packages/core/src/AvatarGroup/index.ts (exports if types change)
@@ -53,7 +59,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
  * </AvatarGroup>
  * ```
  */
-export declare function AvatarGroup({ children, size, 'data-testid': testId, 'aria-label': ariaLabelFromProps, xstyle, className, style, ref, ...props }: AvatarGroupProps): ReactNode;
+export declare function AvatarGroup({ children, size, 'data-testid': testId, 'aria-label': ariaLabelFromProps, 'aria-describedby': ariaDescribedByFromProps, onKeyDown, onFocus, xstyle, className, style, ref, ...props }: AvatarGroupProps): ReactNode;
 export declare namespace AvatarGroup {
     var displayName: string;
 }

package/dist/AvatarGroup/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AASvD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA6B9B;yBAvCe,WAAW"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AAavD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,kBAAkB,EAAE,wBAAwB,EAC5C,SAAS,EACT,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CAuE9B;yBApFe,WAAW"}

package/dist/AvatarGroup/AvatarGroup.js

@@ -11,20 +11,30 @@
  * one AvatarGroupOverflow). The group provides overlap styling via
  * context — no child introspection needed.
  *
+ * When the group contains interactive avatars (rendered as links/buttons) or an
+ * interactive AvatarGroupOverflow, it becomes a single Tab stop with roving
+ * arrow-key focus (via useListFocus with hasRovingTabIndex) and exposes a
+ * screen-reader keyboard hint via aria-describedby. A purely static facepile
+ * gets neither — it stays a plain non-focusable group.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AvatarGroup/AvatarGroup.doc.mjs (props table, features)
  * - /packages/core/src/AvatarGroup/index.ts (exports if types change)
  * - /apps/storybook/stories/AvatarGroup.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/AvatarGroup/ (showcase blocks)
  */
-import { useMemo } from 'react';
+import { useId, useMemo, useState } from 'react';
 import { resolveSize } from "../Avatar/index.js";
 import * as stylex from '@stylexjs/stylex';
-import { mergeProps } from "../utils/index.js";
+import { mergeProps, mergeRefs } from "../utils/index.js";
+import { composeEventHandlers } from "../utils/composeEventHandlers.js";
 import { AvatarGroupContext } from "./AvatarGroupContext.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { useListFocus } from "../hooks/useListFocus.js";
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const OVERLAP_RATIO = 0.25;
 const styles = {
   root: {
@@ -57,6 +67,9 @@ export function AvatarGroup({
   size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
+  'aria-describedby': ariaDescribedByFromProps,
+  onKeyDown,
+  onFocus,
   xstyle,
   className,
   style,
@@ -72,18 +85,57 @@ export function AvatarGroup({
     overlap,
     numericSize
   }), [size, overlap, numericSize]);
+
+  // The keyboard hint and roving tab stop only make sense once the group has
+  // interactive children. Detect their presence (and the writing direction for
+  // RTL-correct arrow navigation) from the rendered DOM after commit, matching
+  // how the codebase reads direction elsewhere (`getComputedStyle(el).direction`).
+  const [hasInteractiveItems, setHasInteractiveItems] = useState(false);
+  const [isRtl, setIsRtl] = useState(false);
+
+  // Single tab stop + roving arrow focus over the group's interactive items.
+  // `itemSelector` targets the shared `[data-avatar-item]` marker stamped on
+  // interactive avatars (their rendered <a>/<button>) and on the overflow
+  // button — NOT a tag/role selector — so roving never catches a nested button
+  // inside a custom status/badge slot (O5).
+  const {
+    listRef,
+    handleKeyDown,
+    handleFocus
+  } = useListFocus({
+    itemSelector: '[data-avatar-item]',
+    orientation: 'horizontal',
+    hasRovingTabIndex: true,
+    isRtl
+  });
+  useIsomorphicLayoutEffect(() => {
+    const root = listRef.current;
+    if (!root) {
+      return;
+    }
+    setHasInteractiveItems(root.querySelector('[data-avatar-item]') != null);
+    setIsRtl(getComputedStyle(root).direction === 'rtl');
+  });
+  const hintId = useId();
+  const describedBy = [ariaDescribedByFromProps, hasInteractiveItems ? hintId : null].filter(Boolean).join(' ') || undefined;
   return /*#__PURE__*/_jsx(AvatarGroupContext, {
     value: contextValue,
-    children: /*#__PURE__*/_jsx("div", {
+    children: /*#__PURE__*/_jsxs("div", {
       ...props,
-      ref: ref,
+      ref: mergeRefs(ref, listRef),
       role: "group",
       "aria-label": ariaLabel,
+      "aria-describedby": describedBy,
       "data-testid": testId,
+      onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+      onFocus: composeEventHandlers(onFocus, handleFocus),
       ...mergeProps(themeProps('avatar-group', {
         size
       }), stylex.props(styles.root, xstyle), className, style),
-      children: children
+      children: [children, hasInteractiveItems && /*#__PURE__*/_jsx(VisuallyHidden, {
+        id: hintId,
+        children: t('@astryx.avatarGroup.keyboardHint')
+      })]
     })
   });
 }

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAW5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA4ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}
+{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAW5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA4ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAyDtC;yBAlEe,mBAAmB"}

package/dist/AvatarGroup/AvatarGroupOverflow.js

@@ -117,6 +117,7 @@ export function AvatarGroupOverflow({
       onClick: onClick,
       ...rest,
       "aria-label": label,
+      "data-avatar-item": "",
       ...mergeProps(themeProps('avatar-group-overflow'), stylex.props(styles.base, styles.button, styles.overlap, dynamicStyles.size(numericSize), dynamicStyles.fontSize(numericSize), dynamicStyles.overlap(-overlap), xstyle), className, style),
       children: content
     });

package/dist/astryx.css

@@ -867,6 +867,8 @@
   .x1y3gkto:not(#\#):not(#\#):not(#\#){outline-offset:1px}
   .x1hl8ikr:not(#\#):not(#\#):not(#\#){outline-offset:2px}
   .x1g710d4:not(#\#):not(#\#):not(#\#){outline-offset:var(--_tree-focus-outline-offset,0)}
+  .x1t137rt:not(#\#):not(#\#):not(#\#){outline-style:none}
+  .x1k57tk5:not(#\#):not(#\#):not(#\#){outline-width:0}
   .x9y5y3v:not(#\#):not(#\#):not(#\#){overflow-clip-margin:1px}
   .x1mzt3pk:not(#\#):not(#\#):not(#\#){overflow-wrap:break-word}
   .x1h4wwuj:not(#\#):not(#\#):not(#\#){overflow-wrap:normal}
@@ -1068,11 +1070,14 @@
   .x25t5g8:focus-visible:not(#\#):not(#\#):not(#\#){opacity:1}
   .xof6bs:is(th:hover *):not(#\#):not(#\#):not(#\#){opacity:1}
   .xofkqq2:popover-open:not(#\#):not(#\#):not(#\#){opacity:1}
+  .xzunyri:focus-visible:not(#\#):not(#\#):not(#\#){outline-color:var(--color-accent)}
   .x1edzap1.x1edzap1:where(.x1iwu4tg:has(:focus-visible) *):not(#\#):not(#\#):not(#\#){outline-offset:2px}
   .x7s97pk:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:2px}
   .x81n7kt.x81n7kt:where(.x1tspnpo:has(:focus-visible) *):not(#\#):not(#\#):not(#\#){outline-offset:2px}
   .x13aywxo:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:var(--button-focus-offset)}
   .xh2nty3:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:var(--spacing-0-5)}
+  .x9v5kkp:focus-visible:not(#\#):not(#\#):not(#\#){outline-style:solid}
+  .x784prv:focus-visible:not(#\#):not(#\#):not(#\#){outline-width:2px}
   .xbt4iw:focus-within:not(#\#):not(#\#):not(#\#){pointer-events:auto}
   .x1mqgsch:is([data-astryx-scrolling]):not(#\#):not(#\#):not(#\#){scrollbar-width:none}
   .xgtlewx:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){transform:scaleX(-1)}