@astryxdesign/core 0.1.8 → 0.1.9-canary.1887ee2

package/dist/Avatar/AvatarStatusDot.d.ts

@@ -24,6 +24,13 @@ import type { BaseProps } from '../BaseProps';
  *   }
  * }
  * ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
  */
 export interface AvatarStatusDotVariantMap {
     success: true;
@@ -37,12 +44,14 @@ export type AvatarStatusDotVariant = keyof AvatarStatusDotVariantMap;
 export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
     ref?: React.Ref<HTMLDivElement>;
     /**
-     * The semantic color variant of the dot.
-     * - `success` — green dot (e.g. online, accepted)
-     * - `neutral` — gray dot (e.g. offline, pending)
-     * - `error` — red dot (e.g. busy, rejected)
+     * The semantic variant of the dot. Each variant pairs a colour with a
+     * distinct built-in shape so status is never conveyed by colour alone
+     * (WCAG 2.1 SC 1.4.1):
+     * - `success` — filled green dot (e.g. online, accepted)
+     * - `neutral` — grey ring (e.g. away, offline, pending)
+     * - `error` — red dot with a minus bar (e.g. busy, do not disturb)
      *
-     * Matches the `variant` convention from `StatusDot`.
+     * Matches the `variant` naming convention from `StatusDot`.
      * @default 'success'
      */
     variant?: AvatarStatusDotVariant;
@@ -50,6 +59,11 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
      * Accessible label for the status dot.
      * Describes the meaning of the indicator for screen readers
      * (e.g. "Online", "Accepted", "John Doe is busy").
+     *
+     * Note: inside an Avatar the label is currently not announced — the
+     * Avatar root is `role="img"`, which prunes descendant semantics.
+     * Pass it anyway; composing status into the avatar's accessible name
+     * is a planned Avatar-level fix.
      */
     label?: string;
     /**
@@ -58,6 +72,14 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
      * The icon is automatically sized to fit the dot and hidden
      * at the smallest avatar sizes where there isn't enough room.
      *
+     * A rendered icon replaces the variant's built-in shape glyph, so use a
+     * different icon per status — the same icon on every variant leaves the
+     * statuses distinguishable by colour alone (WCAG 1.4.1). At the smallest
+     * avatar sizes the built-in glyph still shows instead of the icon.
+     * Booleans and empty strings are ignored (safe for `cond && <Icon />`),
+     * but a component that renders nothing still counts as an icon and
+     * suppresses the glyph.
+     *
      * @example
      * ```
      * <AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />
@@ -69,6 +91,12 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
  * A status indicator dot that automatically scales to match the parent
  * Avatar's size.
  *
+ * Each variant pairs a colour with a distinct built-in shape (filled dot,
+ * ring, minus bar) so status stays distinguishable without colour
+ * perception (WCAG 2.1 SC 1.4.1). Themes can target the shape glyph via
+ * the `astryx-avatar-status-dot-glyph` class and its `data-shape`
+ * attribute.
+ *
  * Must be used inside an Avatar's `status` prop so it can read
  * the avatar size from context.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"AvatarStatusDot.d.ts","sourceRoot":"","sources":["../../src/Avatar/AvatarStatusDot.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAM,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAqC5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,yBAAyB,CAAC;AAErE,MAAM,WAAW,oBAAqB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACrE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAkDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,GAAG,EACH,OAAmB,EACnB,KAAK,EACL,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,oBAAoB,qBA6BtB;yBAtCe,eAAe"}
+{"version":3,"file":"AvatarStatusDot.d.ts","sourceRoot":"","sources":["../../src/Avatar/AvatarStatusDot.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAM,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiD5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,yBAAyB,CAAC;AAErE,MAAM,WAAW,oBAAqB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACrE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AA2JD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,GAAG,EACH,OAAmB,EACnB,KAAK,EACL,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,oBAAoB,qBAyCtB;yBAlDe,eAAe"}

package/dist/Avatar/AvatarStatusDot.js

@@ -19,45 +19,57 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars } from "../theme/tokens.stylex.js";
 import { AvatarSizeContext } from "./AvatarSizeContext.js";
-import { mergeProps } from "../utils/index.js";
+import { isRenderable, mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 
 /**
- * Resolves the status dot size, border width, and icon size based on the
- * avatar size.
+ * Discrete size tier of the status dot, derived from the avatar size.
+ * Keys the built-in shape glyph's stroke weight — see `GLYPH_STROKE_WIDTH`.
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Resolves the status dot size, border width, icon size, and size tier
+ * based on the avatar size.
  *
  * Uses discrete size tiers rather than a continuous ratio so the dot
  * looks intentional at every avatar size:
  *
- *   | Avatar size  | Dot  | Border | Icon |
- *   |--------------|------|--------|------|
- *   | ≤ 36px       | 10px | 1px    | —    |
- *   | 40–72px      | 20px | 2px    | 12px |
- *   | ≥ 96px       | 32px | 4px    | 18px |
+ *   | Avatar size  | Tier   | Dot  | Border | Icon | Field | Glyph stroke |
+ *   |--------------|--------|------|--------|------|-------|--------------|
+ *   | ≤ 36px       | small  | 10px | 1px    | —    | 8px   | 1px          |
+ *   | 40–72px      | medium | 20px | 2px    | 12px | 16px  | 1.5px        |
+ *   | ≥ 96px       | large  | 32px | 4px    | 18px | 24px  | 2px          |
+ *
+ * "Field" is the dot's inner field — the dot minus both borders — that the
+ * shape glyph is drawn into; see `GLYPH_STROKE_WIDTH` for the stroke ladder.
  *
  * Icons are not rendered at the smallest tier — there isn't enough
- * room for them to be legible.
+ * room for them to be legible. The built-in shape glyphs (see
+ * `glyphShapeMap`) do render there, so status stays distinguishable
+ * without colour at every size.
  */
-import { jsx as _jsx } from "react/jsx-runtime";
 function resolveStatusDotSize(avatarSize) {
   if (avatarSize <= 36) {
     return {
       dotSize: 10,
       borderWidth: 1,
-      iconSize: 0
+      iconSize: 0,
+      tier: 'small'
     };
   }
   if (avatarSize <= 72) {
     return {
       dotSize: 20,
       borderWidth: 2,
-      iconSize: 12
+      iconSize: 12,
+      tier: 'medium'
     };
   }
   return {
     dotSize: 32,
     borderWidth: 4,
-    iconSize: 18
+    iconSize: 18,
+    tier: 'large'
   };
 }
 
@@ -73,6 +85,13 @@ function resolveStatusDotSize(avatarSize) {
  *   }
  * }
  * ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
  */
 
 /**
@@ -92,21 +111,23 @@ const styles = {
   },
   success: {
     kWkggS: "xdsz4j9",
+    kMwMTN: "xrkvqaz",
     $$css: true
   },
   neutral: {
-    kWkggS: "xdomwnj",
+    kWkggS: "x10xzikg",
+    kMwMTN: "xv1l7n4",
     $$css: true
   },
   error: {
     kWkggS: "x1pjz0fi",
+    kMwMTN: "xrkvqaz",
     $$css: true
   },
   icon: {
     k1xSpc: "x78zum5",
     kGNEyG: "x6s0dn4",
     kjj79g: "xl56j7k",
-    kMwMTN: "xrkvqaz",
     kLWn49: "x14ju556",
     $$css: true
   }
@@ -137,10 +158,105 @@ const variantStyleMap = {
   error: styles.error
 };
 
+/**
+ * Built-in shape glyph per variant, so each status differs by shape and not
+ * only by colour (WCAG 2.1 SC 1.4.1). The glyph is a stroked inline SVG
+ * painted in `currentColor`:
+ * - `ring` — a stroked circle on a surface plate; the dot reads as hollow
+ *   (away/offline).
+ * - `minus` — a round-capped bar across the filled dot; the dot reads as
+ *   "do not disturb" (busy).
+ *
+ * `success` stays the plain filled dot — filled, hollow, and barred are the
+ * three distinct fill topologies. Custom augmented variants have no entry
+ * and render no glyph; see the `AvatarStatusDotVariantMap` docs.
+ */
+
+const glyphShapeMap = {
+  neutral: 'ring',
+  error: 'minus'
+};
+
+/**
+ * Glyph stroke weight per tier, in px of the dot's inner field.
+ *
+ * Roughly `field / 12`, floored at 1px so the smallest tier stays visible.
+ * That lands on the 1 / 1.5 / 2 ladder the rest of the system draws with —
+ * `Icon`'s default set strokes at 1.5 in a 24 viewBox, as does the
+ * `CheckboxInput` checkmark — rather than the 25% band a CSS box cutout
+ * produced, which was several times heavier than any other glyph we ship.
+ */
+const GLYPH_STROKE_WIDTH = {
+  small: 1,
+  medium: 1.5,
+  large: 2
+};
+
+/** Fraction of the inner field the minus bar spans, cap to cap. */
+const MINUS_BAR_SPAN = 0.75;
+
+/**
+ * The built-in shape glyph, drawn as a stroked inline SVG in `currentColor`.
+ *
+ * Stroking (rather than a CSS box) is what buys sub-pixel control and round
+ * line caps, so the mark stays intentional at every tier — including the
+ * 10px dot, where a box cutout can only land on whole pixels.
+ *
+ * `viewBox` is one user unit per px of the inner field, so every value here
+ * is literal px.
+ */
+function StatusDotGlyph({
+  shape,
+  field,
+  stroke
+}) {
+  const center = field / 2;
+  return /*#__PURE__*/_jsx("svg", {
+    "aria-hidden": "true",
+    viewBox: `0 0 ${field} ${field}`,
+    width: field,
+    height: field,
+    fill: "none",
+    ...themeProps('avatar-status-dot-glyph', {
+      shape
+    }),
+    children: shape === 'ring' ?
+    /*#__PURE__*/
+    // Radius is to the stroke centreline, so the ring's outer edge lands
+    // exactly on the inner field and never clips against the border.
+    _jsx("circle", {
+      cx: center,
+      cy: center,
+      r: (field - stroke) / 2,
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: stroke
+    }) :
+    /*#__PURE__*/
+    // Ends inset by half the stroke so the round caps land inside the
+    // span rather than overhanging it.
+    _jsx("line", {
+      x1: field * (1 - MINUS_BAR_SPAN) / 2 + stroke / 2,
+      y1: center,
+      x2: field * (1 + MINUS_BAR_SPAN) / 2 - stroke / 2,
+      y2: center,
+      stroke: "currentColor",
+      strokeWidth: stroke,
+      strokeLinecap: "round"
+    })
+  });
+}
+
 /**
  * A status indicator dot that automatically scales to match the parent
  * Avatar's size.
  *
+ * Each variant pairs a colour with a distinct built-in shape (filled dot,
+ * ring, minus bar) so status stays distinguishable without colour
+ * perception (WCAG 2.1 SC 1.4.1). Themes can target the shape glyph via
+ * the `astryx-avatar-status-dot-glyph` class and its `data-shape`
+ * attribute.
+ *
  * Must be used inside an Avatar's `status` prop so it can read
  * the avatar size from context.
  *
@@ -172,9 +288,14 @@ export function AvatarStatusDot({
   const {
     dotSize,
     borderWidth,
-    iconSize
+    iconSize,
+    tier
   } = resolveStatusDotSize(avatarSize);
-  return /*#__PURE__*/_jsx("div", {
+  const showsIcon = isRenderable(icon) && iconSize > 0;
+  // A rendered icon is itself a non-colour mark; overlaying both cutouts in
+  // the dot's small inner field would make each illegible.
+  const glyphShape = showsIcon ? undefined : glyphShapeMap[variant];
+  return /*#__PURE__*/_jsxs("div", {
     ...props,
     ref: ref,
     ...(label ? {
@@ -184,11 +305,15 @@ export function AvatarStatusDot({
     ...mergeProps(themeProps('avatar-status-dot', {
       variant
     }), stylex.props(styles.dot, variantStyleMap[variant], dynamicStyles.size(dotSize, borderWidth), xstyle), className, style),
-    children: icon && iconSize > 0 && /*#__PURE__*/_jsx("span", {
+    children: [showsIcon && /*#__PURE__*/_jsx("span", {
       "aria-hidden": "true",
       ...stylex.props(styles.icon, dynamicStyles.iconSize(iconSize)),
       children: icon
-    })
+    }), glyphShape && /*#__PURE__*/_jsx(StatusDotGlyph, {
+      shape: glyphShape,
+      field: dotSize - borderWidth * 2,
+      stroke: GLYPH_STROKE_WIDTH[tier]
+    })]
   });
 }
 AvatarStatusDot.displayName = 'AvatarStatusDot';

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/Banner/Banner.d.ts

@@ -28,6 +28,7 @@
  */
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
+import type { Elevation } from '../utils/types';
 /**
  * Extensible status map for Banner.
  *
@@ -125,6 +126,13 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
      * @default 'card'
      */
     container?: BannerContainer;
+    /**
+     * Resting elevation — the shadow depth the banner sits at. Use for a
+     * floating banner that hovers above content. `none` is the default inline
+     * banner.
+     * @default 'none'
+     */
+    elevation?: Elevation;
     /**
      * Whether the content area (children) starts expanded.
      * Only relevant when children are provided.
@@ -183,7 +191,7 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
  * </Banner>
  * ```
  */
-export declare function Banner({ status, title, description, icon, isDismissable, onDismiss, endContent, container, defaultIsExpanded, children, xstyle, className, style, ref, ...rest }: BannerProps): import("react").JSX.Element | null;
+export declare function Banner({ status, title, description, icon, isDismissable, onDismiss, endContent, container, elevation, defaultIsExpanded, children, xstyle, className, style, ref, ...rest }: BannerProps): import("react").JSX.Element | null;
 export declare namespace Banner {
     var displayName: string;
 }

package/dist/Banner/Banner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../../src/Banner/Banner.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAuB5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA8JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,KAAK,EACL,WAAW,EACX,IAAI,EACJ,aAAqB,EACrB,SAAS,EACT,UAAU,EACV,SAAkB,EAClB,iBAAyB,EACzB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,WAAW,sCAkIb;yBAlJe,MAAM"}
+{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../../src/Banner/Banner.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAgB5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAS9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA+KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,KAAK,EACL,WAAW,EACX,IAAI,EACJ,aAAqB,EACrB,SAAS,EACT,UAAU,EACV,SAAkB,EAClB,SAAkB,EAClB,iBAAyB,EACzB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,WAAW,sCAmJb;yBApKe,MAAM"}

package/dist/Banner/Banner.js

@@ -35,7 +35,7 @@ import * as stylex from '@stylexjs/stylex';
 import { Button } from "../Button/index.js";
 import { Icon } from "../Icon/index.js";
 import "../theme/tokens.stylex.js";
-import { colorVars, spacingVars, radiusVars, fontWeightVars, typeScaleVars, borderVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, radiusVars, fontWeightVars, typeScaleVars, borderVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { edgeCompSlot } from "../Layout/edgeCompensation.stylex.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -130,6 +130,10 @@ const styles = {
     kMv6JI: "xjb2p0i",
     $$css: true
   },
+  rootElevatedCard: {
+    kaIpWk: "x1hviunn",
+    $$css: true
+  },
   header: {
     k1xSpc: "x78zum5",
     kGNEyG: "x1cy8zhl",
@@ -182,6 +186,30 @@ const statusStyles = {
   }
 };
 
+// Resting elevation for the banner. Applied to the root so the shadow wraps
+// the whole banner (header + optional content). 'none' is the default and
+// leaves the layout-only root untouched. For the `card` container the root is
+// rounded (rootElevatedCard) so the shadow follows the card silhouette; the
+// full-width `section` container stays square.
+const elevationStyles = {
+  none: {
+    kGVxlE: "x1gnnqk1",
+    $$css: true
+  },
+  low: {
+    kGVxlE: "x1i5ehqx",
+    $$css: true
+  },
+  med: {
+    kGVxlE: "x14hfi27",
+    $$css: true
+  },
+  high: {
+    kGVxlE: "x1kcpxr7",
+    $$css: true
+  }
+};
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -240,6 +268,7 @@ export function Banner({
   onDismiss,
   endContent,
   container = 'card',
+  elevation = 'none',
   defaultIsExpanded = false,
   children,
   xstyle,
@@ -282,7 +311,7 @@ export function Banner({
   return /*#__PURE__*/_jsxs("div", {
     ref: ref,
     role: role,
-    ...mergeProps(stylex.props(styles.root, xstyle), className, style),
+    ...mergeProps(stylex.props(styles.root, elevationStyles[elevation], isCard && elevation !== 'none' && styles.rootElevatedCard, xstyle), className, style),
     ...rest,
     children: [/*#__PURE__*/_jsxs("div", {
       ...mergeProps(themeProps('banner', {
@@ -363,10 +392,10 @@ export function Banner({
         status
       }), {
         0: {
-          className: "x1de1mus x8o8v82 x1pzlopt x1i535u5 x1pcaw5z x92x3c3 x19ypqd9 x32b0ac x1q0q8m5 x1utcnwd xtgwc6q xw8gpjh"
+          className: "x1de1mus x8o8v82 x1pzlopt xgbv0en xw8tdv1 x92x3c3 x1t7ytsu x18b5jzi x1q0q8m5 x1j92z86 x1gejf6u xw8gpjh"
         },
         1: {
-          className: "x1de1mus x8o8v82 x1pzlopt x1i535u5 x1pcaw5z x92x3c3 x19ypqd9 x32b0ac x1q0q8m5 x1utcnwd xtgwc6q xw8gpjh xv76oww x1padx2d"
+          className: "x1de1mus x8o8v82 x1pzlopt xgbv0en xw8tdv1 x92x3c3 x1t7ytsu x18b5jzi x1q0q8m5 x1j92z86 x1gejf6u xw8gpjh xv76oww x1padx2d"
         }
       }[!!isCard << 0]),
       children: children

package/dist/Breadcrumbs/BreadcrumbItem.d.ts

@@ -1,9 +1,15 @@
 /**
  * @file BreadcrumbItem.tsx
- * @input Uses React use/useRef/useEffect, stylex, theme tokens, BreadcrumbContext
+ * @input Uses React use/useRef/useEffect, stylex, theme tokens, BreadcrumbContext,
+ *   and (for the menu trigger) usePopover + the shared DropdownMenu item API
+ *   (renderDropdownItems, DropdownMenuContext, MENU_ITEM_SELECTOR, useListFocus)
  * @output Exports BreadcrumbItem component and BreadcrumbItemProps
  * @position Individual breadcrumb item; used inside Breadcrumbs
  *
+ * A `menu` prop turns the item's link-styled button into a menu trigger whose
+ * popover reuses DropdownMenu's item pipeline — the same wiring ContextMenu
+ * uses — so menu-item definitions are portable across the menu family.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
  * - /packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx
@@ -14,6 +20,8 @@
 import React, { type ReactNode, type MouseEvent } from 'react';
 import type { LinkComponentType } from '../Link/types';
 import type { BaseProps } from '../BaseProps';
+import { type DropdownMenuSize } from '../DropdownMenu/DropdownMenuContext';
+import type { DropdownMenuOption } from '../DropdownMenu/DropdownMenu';
 export interface BreadcrumbItemProps extends Omit<BaseProps<HTMLLIElement>, 'onClick'> {
     ref?: React.Ref<HTMLLIElement>;
     /**
@@ -44,6 +52,27 @@ export interface BreadcrumbItemProps extends Omit<BaseProps<HTMLLIElement>, 'onC
      * Optional icon rendered before the label.
      */
     startIcon?: ReactNode;
+    /**
+     * Menu opened when the item is activated. Accepts the SAME item API as
+     * DropdownMenu / MoreMenu / ContextMenu, so a consumer's existing menu-item
+     * definitions are portable into a breadcrumb with no rewrite:
+     * - a `DropdownMenuOption[]` data array (items, sections, dividers), or
+     * - composed `DropdownMenuItem` / `DropdownMenuCheckboxItem` /
+     *   `DropdownMenuRadioGroup` children.
+     *
+     * When set, the item renders as a link-styled menu trigger (button + a
+     * trailing chevron, `aria-haspopup="menu"` / `aria-expanded`) whose popover
+     * is a `role="menu"` container that provides `DropdownMenuContext` and runs
+     * `useListFocus`. Takes precedence over `href` / `onClick` (which are
+     * ignored when `menu` is set — a dev-time warning is logged).
+     */
+    menu?: DropdownMenuOption[] | ReactNode;
+    /**
+     * Size passed to the menu items via `DropdownMenuContext` (item
+     * padding/typography). Defaults from the breadcrumb variant:
+     * `'supporting'` → `'sm'`, otherwise `'md'`.
+     */
+    menuSize?: DropdownMenuSize;
 }
 /**
  * An individual breadcrumb item. Renders as a link (`<a>`) or a span
@@ -59,7 +88,7 @@ export interface BreadcrumbItemProps extends Omit<BaseProps<HTMLLIElement>, 'onC
  * <BreadcrumbItem isCurrent>My Project</BreadcrumbItem>
  * ```
  */
-export declare function BreadcrumbItem({ ref, as, children, href, onClick, isCurrent: isCurrentProp, startIcon, xstyle, className, style, 'data-testid': testId, ...rest }: BreadcrumbItemProps): React.JSX.Element;
+export declare function BreadcrumbItem({ ref, as, children, href, onClick, isCurrent: isCurrentProp, startIcon, menu, menuSize, xstyle, className, style, 'data-testid': testId, ...rest }: BreadcrumbItemProps): React.JSX.Element;
 export declare namespace BreadcrumbItem {
     var displayName: string;
 }