@astryxdesign/core 0.4.5-canary.82a416a → 0.4.5-canary.8a9d85f

package/dist/Avatar/Avatar.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ * @input Uses React, HTMLAttributes, ReactNode, useState, useRef; useTooltip
  *   (Tooltip hook) for the optional name-on-hover tooltip; useTranslator (i18n)
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
@@ -8,6 +8,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Avatar/index.ts (exports if types change)
+ * - /packages/core/src/Avatar/AvatarStatusLabelContext.ts (the status label ref)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  *
@@ -76,10 +77,14 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
      * Content displayed in the corner of the avatar.
      * Typically used for status indicators or badges.
      *
-     * When the element carries a string `label` prop (as `AvatarStatusDot`
-     * does), the label is composed into the avatar's accessible name
-     * (e.g. "Jane Doe, Online") so assistive tech can reach the status —
-     * the `role="img"` root prunes descendant semantics (WCAG 4.1.2).
+     * `AvatarStatusDot` reports its own `label` to the avatar, which composes
+     * it into the avatar's accessible name (e.g. "Jane Doe, Online") so
+     * assistive tech can reach the status: the `role="img"` root prunes
+     * descendant semantics (WCAG 4.1.2). Reporting goes through context, so it
+     * still works when the dot sits inside a wrapper component of your own. A
+     * custom status element that is not an `AvatarStatusDot` names itself the
+     * same way, by rendering an `AvatarStatusDot` or by carrying a string
+     * `label` prop.
      */
     status?: ReactNode;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAoC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiB5C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AA4BrD;;;;;;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;AA6HD,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;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;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;AA0DD;;;;;;;;;;;;;;;;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,+BA+Pb;yBAlRe,MAAM"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAA4C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAqB5C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AA4BrD;;;;;;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;AAgID,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;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;OAYG;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;AAwHD;;;;;;;;;;;;;;;;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,+BAmUb;yBAtVe,MAAM"}

package/dist/Avatar/Avatar.js

@@ -4,7 +4,7 @@
 
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ * @input Uses React, HTMLAttributes, ReactNode, useState, useRef; useTooltip
  *   (Tooltip hook) for the optional name-on-hover tooltip; useTranslator (i18n)
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
@@ -12,16 +12,18 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Avatar/index.ts (exports if types change)
+ * - /packages/core/src/Avatar/AvatarStatusLabelContext.ts (the status label ref)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  *
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
-import { isValidElement, useMemo, useState } from 'react';
+import { isValidElement, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, typographyVars, fontWeightVars, radiusVars } from "../theme/tokens.stylex.js";
 import { AvatarSizeContext } from "./AvatarSizeContext.js";
+import { AvatarStatusLabelContext } from "./AvatarStatusLabelContext.js";
 import { useAvatarGroup } from "../AvatarGroup/AvatarGroupContext.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -134,7 +136,7 @@ const styles = {
     kMwMTN: "x1heor9g",
     kVVagm: "xln7xf2",
     kybGjl: "x1hl2dhg",
-    kkrTdU: "x1ypdohk",
+    kkrTdU: "x1ypdohk x16khyan",
     kaIpWk: "xjspbzw",
     $$css: true
   }
@@ -217,13 +219,13 @@ function getInitials(name) {
 
 /**
  * Reads the accessible status label off the `status` element, when it
- * exposes one. `AvatarStatusDot`'s `label` prop is the canonical source,
- * but any custom status element with a string `label` prop participates.
+ * exposes one.
  *
- * The avatar root is `role="img"`, which prunes ALL descendant semantics
- * from the accessibility tree — a label inside the status subtree is never
- * announced on its own. Composing it into the avatar's own accessible name
- * is the only way the status reaches assistive tech (WCAG 4.1.2).
+ * Only sees a literal `label` prop on the element the consumer passes, so a
+ * consumer's own wrapper around the dot hides it — that case comes in through
+ * `AvatarStatusLabelContext` instead. Kept because it answers the first
+ * render, before any report has landed, and because it tracks a label that
+ * changes on an element that does not report at all.
  */
 function getStatusLabel(status) {
   if (! /*#__PURE__*/isValidElement(status)) {
@@ -235,6 +237,60 @@ function getStatusLabel(status) {
   return typeof label === 'string' && label !== '' ? label : undefined;
 }
 
+/**
+ * The string when it carries something, `undefined` when it is absent or
+ * blank. An empty accessible name is meaningless, so a blank reads as
+ * absent, the way Icon treats `label=""`.
+ */
+function meaningful(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+
+/**
+ * Derives the root's ARIA attributes from the resolved accessible name,
+ * following Icon's `getIconA11yProps`.
+ *
+ * - A name → meaningful image: `role="img"` + `aria-label`.
+ * - No name → decorative: `role="presentation"` + `aria-hidden="true"`, rather
+ *   than announcing a meaningless generic "Avatar" (obs-9).
+ *
+ * The result is spread BEFORE `{...props}` on every root so an explicit
+ * `aria-label` / `role` / `aria-hidden` from the consumer always wins.
+ */
+function getAvatarA11yProps(accessibleName) {
+  return accessibleName != null && accessibleName !== '' ? {
+    role: 'img',
+    'aria-label': accessibleName
+  } : {
+    role: 'presentation',
+    'aria-hidden': 'true'
+  };
+}
+
+/**
+ * The avatar's accessible name: its own name, the status label, or the two
+ * composed ("Jane Doe, Online"). Used both by render and by the commit-phase
+ * update, so the two can never compose differently.
+ */
+function composeAccessibleName(t, nameLabel, statusLabel) {
+  if (nameLabel && statusLabel) {
+    return t('@astryx.avatar.nameWithStatus', {
+      name: nameLabel,
+      status: statusLabel
+    });
+  }
+  return nameLabel || statusLabel;
+}
+
+/** Sets an attribute, or removes it when the value is absent. */
+function setAttributeOrRemove(element, name, value) {
+  if (value == null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+
 /**
  * Default person icon SVG for when no image or name is provided
  */
@@ -299,8 +355,8 @@ export function Avatar({
   // A whitespace-only string carries no identity. Without this it produces no
   // initials (getInitials trims to nothing) and no default icon (a space is
   // truthy), leaving an empty plate behind a blank accessible name.
-  const meaningfulName = name?.trim() ? name : undefined;
-  const meaningfulAlt = alt?.trim() ? alt : undefined;
+  const meaningfulName = meaningful(name);
+  const meaningfulAlt = meaningful(alt);
   const showInitials = !showImage && !showFallbackImage && meaningfulName;
   const showIcon = !showImage && !showFallbackImage && !meaningfulName;
 
@@ -314,12 +370,17 @@ export function Avatar({
   // generic "Avatar" (obs-9).
   const t = useTranslator();
   const nameLabel = meaningfulAlt || meaningfulName;
-  const statusLabel = getStatusLabel(status);
-  const accessibleName = nameLabel && statusLabel ? t('@astryx.avatar.nameWithStatus', {
-    name: nameLabel,
-    status: statusLabel
-  }) : nameLabel || statusLabel;
-  const isDecorative = !accessibleName;
+  // This render can only see a label introspected off a directly-passed
+  // element. A status inside a consumer's own wrapper reports through the ref
+  // below, in the commit phase, and lands on the root element from there.
+  const accessibleName = composeAccessibleName(t, nameLabel, getStatusLabel(status));
+  const a11yProps = getAvatarA11yProps(accessibleName);
+  // An `<a>`/`<button>` root carries its own role and must not be hidden, so
+  // only the name transfers. Spread before `{...props}` for the same
+  // consumer-wins precedence as the static root.
+  const a11yLabelProps = accessibleName ? {
+    'aria-label': accessibleName
+  } : undefined;
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
@@ -351,8 +412,8 @@ export function Avatar({
     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);
+  // interactive), so the tooltip works for link/button avatars too. The root
+  // ref itself is assembled below, once the element swap is resolved.
   const describedByProp = showTooltip && isCustomTooltip ? {
     'aria-describedby': [props['aria-describedby'], tooltipHook.describedBy].filter(Boolean).join(' ') || undefined
   } : null;
@@ -365,10 +426,57 @@ export function Avatar({
   const isInteractive = renderAsLink || renderAsButton;
   const LinkComponent = useLinkComponent(as);
 
-  // An interactive control with no accessible name is an unacceptable control
-  // name. `useDevWarning` is the shared guardrail: it warns once per mount
-  // rather than on every render, and compiles out of production builds.
-  useDevWarning('Avatar', 'an interactive avatar (with `href` or `onClick`) needs a meaningful ' + 'accessible name. Pass `alt` or `name`.', isInteractive && !accessibleName);
+  // An interactive control needs an identity of its own. A status label is not
+  // one: it composes into the accessible name, so `<Avatar href status={<dot
+  // label="Online" />} />` resolves a name that reads as legitimate and says
+  // nothing about who the link points at. Only `alt`/`name` count, or a
+  // consumer's own `aria-label`/`aria-labelledby` escape hatch, which wins
+  // over the derived props below.
+  const consumerName = meaningful(props['aria-label']) ?? meaningful(props['aria-labelledby']);
+  useDevWarning('Avatar', 'an interactive avatar (with `href` or `onClick`) needs a meaningful ' + 'accessible name. Pass `alt` or `name`.', isInteractive && !nameLabel && consumerName == null);
+
+  // A status inside a consumer's own wrapper is invisible to render: the dot
+  // writes its label into this ref from its own callback ref, in the commit
+  // phase. A ref write cannot re-render, so the composed name is written
+  // straight onto the root element instead — still before paint, and with no
+  // second render.
+  const statusLabelRef = useRef({
+    label: undefined,
+    update: null
+  });
+  // A fresh callback ref every render, so React reattaches it on every commit
+  // and the name is recomposed after React has written this render's props.
+  // `update` covers the other direction: a label that changes while the avatar
+  // itself does not re-render.
+  const nameRef = element => {
+    if (element == null) {
+      return;
+    }
+    const target = statusLabelRef.current;
+    target.update = () => {
+      const composed = composeAccessibleName(t, nameLabel, meaningful(target.label) ?? getStatusLabel(status));
+      // A consumer's own ARIA wins here exactly as it does in render, where
+      // the derived props spread before `{...props}`.
+      if (props['aria-label'] == null) {
+        setAttributeOrRemove(element, 'aria-label', composed);
+      }
+      // An `<a>`/`<button>` root carries its own role and must not be hidden,
+      // so only the name transfers there.
+      if (!isInteractive) {
+        if (props.role == null) {
+          element.setAttribute('role', composed ? 'img' : 'presentation');
+        }
+        if (props['aria-hidden'] == null) {
+          setAttributeOrRemove(element, 'aria-hidden', composed ? undefined : 'true');
+        }
+      }
+    };
+    target.update();
+    return () => {
+      target.update = null;
+    };
+  };
+  const rootRef = mergeRefs(ref, showTooltip ? tooltipHook.ref : undefined, nameRef);
 
   // The inner visuals are identical across the static and interactive variants.
   const visualContent = /*#__PURE__*/_jsxs(_Fragment, {
@@ -430,13 +538,13 @@ export function Avatar({
     // 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, {
+      ...a11yLabelProps,
       ...interactivePassthrough,
       ...describedByProp,
       ref: rootRef,
       href: href,
       target: target,
       rel: rel,
-      "aria-label": accessibleName,
       "data-avatar-item": "",
       "data-testid": testId,
       onClick: onClick,
@@ -445,11 +553,11 @@ export function Avatar({
     });
   } else if (renderAsButton) {
     rootElement = /*#__PURE__*/_jsx("button", {
+      ...a11yLabelProps,
       ...interactivePassthrough,
       ...describedByProp,
       ref: rootRef,
       type: "button",
-      "aria-label": accessibleName,
       "data-avatar-item": "",
       "data-testid": testId,
       onClick: onClick,
@@ -458,11 +566,9 @@ export function Avatar({
     });
   } else {
     rootElement = /*#__PURE__*/_jsx("div", {
+      ...a11yProps,
       ...props,
-      ref: rootRef,
-      role: isDecorative ? 'presentation' : 'img',
-      "aria-label": isDecorative ? undefined : accessibleName,
-      "aria-hidden": isDecorative || undefined
+      ref: rootRef
       // 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. Suppressed inside
@@ -477,7 +583,10 @@ export function Avatar({
   }
   const avatarElement = /*#__PURE__*/_jsx(AvatarSizeContext, {
     value: numericSize,
-    children: rootElement
+    children: /*#__PURE__*/_jsx(AvatarStatusLabelContext, {
+      value: statusLabelRef,
+      children: rootElement
+    })
   });
 
   // Always return the same structure so the avatar keeps its position in the

package/dist/Avatar/AvatarStatusDot.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file AvatarStatusDot.tsx
- * @input Uses React, StyleX, theme tokens, and AvatarSizeContext
+ * @input Uses React, StyleX, theme tokens, AvatarSizeContext, and
+ *   AvatarStatusLabelContext (label reporting)
  * @output Exports AvatarStatusDot component and AvatarStatusDotProps type
  * @position Sub-component of Avatar; renders a size-aware status indicator
  *

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;AAM5C,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,SAAS,CAAC;AA4CvD;;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;;;;;;;;;;;OAWG;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"}
+{"version":3,"file":"AvatarStatusDot.d.ts","sourceRoot":"","sources":["../../src/Avatar/AvatarStatusDot.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAA4B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,SAAS,CAAC;AA4CvD;;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;;;;;;;;;;;OAWG;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,qBAiEtB;yBA1Ee,eAAe"}

package/dist/Avatar/AvatarStatusDot.js

@@ -4,7 +4,8 @@
 
 /**
  * @file AvatarStatusDot.tsx
- * @input Uses React, StyleX, theme tokens, and AvatarSizeContext
+ * @input Uses React, StyleX, theme tokens, AvatarSizeContext, and
+ *   AvatarStatusLabelContext (label reporting)
  * @output Exports AvatarStatusDot component and AvatarStatusDotProps type
  * @position Sub-component of Avatar; renders a size-aware status indicator
  *
@@ -14,12 +15,13 @@
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  */
-import React, { use } from 'react';
+import React, { use, useCallback, useMemo } from 'react';
 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 { isRenderable, mergeProps } from "../utils/index.js";
+import { AvatarStatusLabelContext } from "./AvatarStatusLabelContext.js";
+import { isRenderable, mergeProps, mergeRefs } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 
 /**
@@ -264,6 +266,30 @@ export function AvatarStatusDot({
   ...props
 }) {
   const avatarSize = use(AvatarSizeContext);
+  const statusLabelRef = use(AvatarStatusLabelContext);
+  // Report the label through the avatar's ref from a callback ref rather than
+  // an Effect: the ref runs in the commit phase, so the avatar's accessible
+  // name is composed before paint, and a ref write costs no render.
+  /* eslint-disable react-compiler/react-compiler -- the avatar shares its own
+     ref through context so the dot can write into it; a context read looks
+     immutable to the compiler */
+  const reportRef = useCallback(() => {
+    const target = statusLabelRef?.current;
+    if (target == null) {
+      return;
+    }
+    target.label = label;
+    target.update?.();
+    return () => {
+      target.label = undefined;
+      target.update?.();
+    };
+  }, [statusLabelRef, label]);
+  /* eslint-enable react-compiler/react-compiler */
+  // Memoized so React only detaches and reattaches when the reported label
+  // actually changes; an inline merge would withdraw and re-report on every
+  // render of the avatar.
+  const rootRef = useMemo(() => mergeRefs(ref, reportRef), [ref, reportRef]);
   const {
     dotSize,
     borderWidth,
@@ -276,7 +302,7 @@ export function AvatarStatusDot({
   const glyphShape = showsIcon ? undefined : glyphShapeMap[variant];
   return /*#__PURE__*/_jsxs("div", {
     ...props,
-    ref: ref,
+    ref: rootRef,
     ...(label ? {
       role: 'img',
       'aria-label': label

package/dist/Avatar/AvatarStatusLabelContext.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file AvatarStatusLabelContext.ts
+ * @input Uses React createContext, RefObject
+ * @output Exports AvatarStatusLabelContext, AvatarStatusLabelTarget
+ * @position Internal context; provided by Avatar, consumed by AvatarStatusDot
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Avatar/Avatar.doc.mjs
+ */
+import { type RefObject } from 'react';
+/**
+ * The box a status element writes its label into.
+ *
+ * `update` is the avatar's own recompose, set while its root element is
+ * attached and null otherwise. Writing `label` alone is enough on mount (the
+ * avatar reads the box when its root attaches, which happens after its
+ * children's refs); calling `update` covers a label that changes later
+ * without the avatar itself re-rendering.
+ */
+export interface AvatarStatusLabelTarget {
+    label: string | undefined;
+    update: (() => void) | null;
+}
+/**
+ * Lets a status element hand its accessible label to the enclosing Avatar,
+ * which composes it into its own accessible name ("Jane Doe, Online").
+ *
+ * The avatar root is `role="img"`, which prunes all descendant semantics, so
+ * composing the label in is the only way the status reaches assistive tech
+ * (WCAG 4.1.2). Reading `label` off the passed element only works when the
+ * consumer passes `AvatarStatusDot` directly; this route works through a
+ * consumer's own wrapper, at any depth.
+ *
+ * The value is a ref, written from the dot's own callback ref in the commit
+ * phase, so reporting a label costs no render and no state. `null` outside an
+ * Avatar, where a standalone dot names itself and has nobody to report to.
+ */
+export declare const AvatarStatusLabelContext: import("react").Context<RefObject<AvatarStatusLabelTarget> | null>;
+//# sourceMappingURL=AvatarStatusLabelContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AvatarStatusLabelContext.d.ts","sourceRoot":"","sources":["../../src/Avatar/AvatarStatusLabelContext.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAAgB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,oEAC2B,CAAC"}

package/dist/Avatar/AvatarStatusLabelContext.js

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AvatarStatusLabelContext.ts
+ * @input Uses React createContext, RefObject
+ * @output Exports AvatarStatusLabelContext, AvatarStatusLabelTarget
+ * @position Internal context; provided by Avatar, consumed by AvatarStatusDot
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Avatar/Avatar.doc.mjs
+ */
+import { createContext } from 'react';
+
+/**
+ * The box a status element writes its label into.
+ *
+ * `update` is the avatar's own recompose, set while its root element is
+ * attached and null otherwise. Writing `label` alone is enough on mount (the
+ * avatar reads the box when its root attaches, which happens after its
+ * children's refs); calling `update` covers a label that changes later
+ * without the avatar itself re-rendering.
+ */
+
+/**
+ * Lets a status element hand its accessible label to the enclosing Avatar,
+ * which composes it into its own accessible name ("Jane Doe, Online").
+ *
+ * The avatar root is `role="img"`, which prunes all descendant semantics, so
+ * composing the label in is the only way the status reaches assistive tech
+ * (WCAG 4.1.2). Reading `label` off the passed element only works when the
+ * consumer passes `AvatarStatusDot` directly; this route works through a
+ * consumer's own wrapper, at any depth.
+ *
+ * The value is a ref, written from the dot's own callback ref in the commit
+ * phase, so reporting a label costs no render and no state. `null` outside an
+ * Avatar, where a standalone dot names itself and has nobody to report to.
+ */
+export const AvatarStatusLabelContext = /*#__PURE__*/createContext(null);
+AvatarStatusLabelContext.displayName = 'AvatarStatusLabelContext';

package/dist/AvatarGroup/AvatarGroup.d.ts

@@ -32,7 +32,9 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
      */
     children: ReactNode;
     /**
-     * Size applied to all avatars via context.
+     * Size applied to all avatars via context. This wins over each child
+     * Avatar's own `size` prop, including when it is left at the default, so
+     * set the size here rather than on the children.
      * @default 'md'
      */
     size?: AvatarSize;

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

@@ -1 +1 @@
-{"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,CAmE9B;yBAhFe,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;;;;;OAKG;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,CAmE9B;yBAhFe,WAAW"}

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;AAQ5C,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;AAoED;;;;;;;;;;;;;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,CA2DtC;yBApEe,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;AAa5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,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;AAqFD;;;;;;;;;;;;;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,CA+DtC;yBAxEe,mBAAmB"}

package/dist/AvatarGroup/AvatarGroupOverflow.js

@@ -15,8 +15,9 @@
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { colorVars, typographyVars, fontWeightVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
+import { colorVars, typographyVars, typeScaleVars, fontWeightVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
+import { resolveSize } from "../Avatar/index.js";
 import { useAvatarGroup } from "./AvatarGroupContext.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
@@ -27,7 +28,7 @@ const OVERFLOW_FONT_RATIO = 0.35;
 const styles = {
   base: {
     kVAEAm: "x1n2onr6",
-    k1xSpc: "x78zum5",
+    k1xSpc: "x3nfvp2",
     kGNEyG: "x6s0dn4",
     kjj79g: "xl56j7k",
     kaIpWk: "xjspbzw",
@@ -45,13 +46,13 @@ const styles = {
     $$css: true
   },
   button: {
-    kkrTdU: "x1ypdohk",
+    kkrTdU: "x1ypdohk x16khyan",
     k8WAf4: "xt970qd",
     kKwaWg: "x14bno8m x1otsd3y x1nocapi",
     $$css: true
   },
   overlap: {
-    keTefX: "x13hpdyo",
+    keTefX: "x1sik18w",
     $$css: true
   }
 };
@@ -74,7 +75,7 @@ const dynamicStyles = {
     "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s + BORDER_WIDTH * 2)
   }],
   fontSize: s => [_temp2, {
-    "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s * OVERFLOW_FONT_RATIO)
+    "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(`max(${typeScaleVars['--text-supporting-size']}, ${s * OVERFLOW_FONT_RATIO}px)`)
   }],
   overlap: offset => [_temp3, {
     "--x---_avatar-group-overlap": `${offset}px` != null ? `${offset}px` : undefined
@@ -108,12 +109,17 @@ export function AvatarGroupOverflow({
   const t = useTranslator();
   const group = useAvatarGroup();
   const size = group?.size ?? 'md';
-  const numericSize = group?.numericSize ?? 36;
+  const numericSize = group?.numericSize ?? resolveSize('md');
   const overlap = group?.overlap ?? 0;
+
+  // count is a plain number, and the documented shape for it is
+  // `total - visibleCount`, which goes negative whenever the list is shorter
+  // than the slice. Clamping keeps that from rendering "+-3".
+  const safeCount = Math.max(0, count);
   const label = t('@astryx.avatarGroup.overflow', {
-    count
+    count: safeCount
   });
-  const content = children ?? `+${count}`;
+  const content = children ?? `+${safeCount}`;
   if (onClick) {
     return /*#__PURE__*/_jsx("button", {
       ref: ref,

package/dist/Blockquote/Blockquote.d.ts

@@ -18,15 +18,16 @@ export interface BlockquoteProps extends BaseProps<HTMLQuoteElement> {
     /** Content of the blockquote */
     children: ReactNode;
     /**
-     * Optional attribution for the quote. Rendered in a <footer> with <cite>.
+     * Optional attribution for the quote. Rendered in a `<cite>` element after
+     * the quoted content.
      */
     cite?: ReactNode;
 }
 /**
  * Blockquote component for displaying quoted content.
  *
- * Renders a semantic `<blockquote>` with an accent-colored left border
- * and secondary text color, matching the Astryx visual language.
+ * Renders a semantic `<blockquote>` with an inline-start rule and secondary
+ * text color, matching the Astryx visual language.
  *
  * @example
  * ```

package/dist/Blockquote/Blockquote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Blockquote.d.ts","sourceRoot":"","sources":["../../src/Blockquote/Blockquote.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,gBAAgB,CAAC;IAClE,qDAAqD;IACrD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC,gCAAgC;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BAmBjB;yBA3Be,UAAU"}
+{"version":3,"file":"Blockquote.d.ts","sourceRoot":"","sources":["../../src/Blockquote/Blockquote.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,gBAAgB,CAAC;IAClE,qDAAqD;IACrD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC,gCAAgC;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAwBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BAmBjB;yBA3Be,UAAU"}