@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @xds/core
 
+# 0.1.9
+
+#### New Features
+
+- Avatar: add a `tooltip?: string | boolean` prop for a name-on-hover tooltip. Omitting it (or `true`) shows the avatar's `name` on hover and keyboard focus; a string shows that text instead (no need to wrap in `Tooltip`); `false` disables it. Avatar owns the tooltip via the existing Tooltip hook, so there's no extra wrapper DOM. Because this adds a default tooltip to every existing named Avatar, set `tooltip={false}` when you supply your own `Tooltip`/`HoverCard` overlay. The root `aria-label` (`alt || name`) is unchanged; the default name tooltip is visual-only (no `aria-describedby` double-announce), while a custom string tooltip is exposed as a description. Decorative avatars (no `name`/`alt`) get no tooltip. (#4164)
+- BreadcrumbItem gains a `menu` prop that turns a crumb into a menu trigger for switching between sibling destinations. It accepts the same item API as DropdownMenu/MoreMenu/ContextMenu (a `DropdownMenuOption[]` array or composed item children), so existing menu-item definitions drop into a breadcrumb with no rewrite. The item components are also re-exported under `Breadcrumb*` aliases.
+- Calendar: make the today/selected day-cell ring precisely themeable. The day cell now reflects a compound `marker` state (`today-only` / `today-in-range`) that maps 1:1 to the treatment actually drawn, so `defineTheme({components: {'calendar-day': {'marker:today-only': {...}}}})` targets exactly those states without over-matching or needing a `:not()` exclusion. Default rendering is unchanged.
+- Calendar: add a dedicated `astryx-calendar-nav` theme target for the prev/next month-nav buttons, so consumers can theme the nav controls (color, radius, per-direction, disabled edge) without reaching every Button via the global `astryx-button` handle. Reflects `nav` (prev/next) and the `disabled` state as data attributes.
+- ChatComposer: make custom inputs first-class. `useChatComposerContext()` and its types are now public, so any input in the `input` slot can read `value`/`onChange`/`onSubmit`/`canSend`/`placeholder`/`isDisabled` and drive the shell's send button. Inputs can register a focus control on `inputControlRef` so click-to-focus works for any input shape (not just `contenteditable`/`textarea`); the shell keeps a DOM-query fallback for uninstrumented inputs.
+- ChatComposerInput: add an `onKeyDown` seam so consumers can host platform- or app-specific key handling — e.g. `preventDefault()` Enter to insert a newline on a touch keyboard, or submit on Cmd/Ctrl+Enter. Enter also no longer submits mid-IME-composition.
+- CommandPalette: add a dedicated `astryx-command-palette-group-heading` theme target on the group heading, so consumers can theme just the heading (e.g. its padding or typography) via `defineTheme` instead of a fragile structural selector. The group root keeps its own `astryx-command-palette-group` target.
+- DateInput gains a `format` prop for the committed date value, reusing Timestamp's `format` vocabulary so the same literal renders the same date shape in both components. Named values are `date_long` (the default, "March 21, 2026"), `date` ("Mar 21, 2026"), `date_weekday` ("Wed, Mar 21, 2026"), and `system_date` ("2026-03-21"); a `(value) => string` function is also accepted for custom output. The `date_long` default is byte-identical to DateInput's previous long-month rendering, so existing usage is unchanged. This also extends Timestamp with two new shared members, `date_long` and `date_weekday`, giving the two components full value parity on the date-only formats. Formatting applies only to the committed value, never to text being typed.
+- Add an `elevation` prop to configurable surfaces — Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner take the full `'none' | 'low' | 'med' | 'high'` scale; ChatComposer takes `'none' | 'low'`. Defaults preserve today's appearance (`none` everywhere except ChatComposer's `low`), so nothing changes unless you opt in. (#4146)
+- OverflowList: add `maxVisibleItems` to cap the number of visible items (the ceiling partner to `minVisibleItems`) and `maxRows` for bounded multi-row wrapping — items wrap onto up to N rows, then collapse into the overflow indicator. Both props are optional and default to off, so single-line behavior is unchanged. See #4176.
+- Add `useTableRowStatus`, a plugin that prepends a narrow column
+  signaling per-row status.
+- Thumbnail: add `showRemoveOn` prop — `'hover'` (default) reveals the remove button on hover or keyboard focus and keeps it visible on touch; `'always'` shows it at rest.
+- Table tree: add an optional expand-all/collapse-all header control (#4142)
+  `useTableTreeState` now returns an aggregate `isAllExpanded` state (`true` / `false` / `'indeterminate'`) and threads `expandAll` / `collapseAll` into `treeConfig`. `useTableTreeData` gains a `hasExpandAllControl` prop: when set, it renders an expand-all/collapse-all toggle in the tree column header, wired to that state, so consumers no longer need to hand-roll external buttons. Flat data stays a full no-op. This is the first affordance folded in from `useTableRowExpansion` as part of converging the two tree plugins.
+- TreeList: add a dedicated `astryx-tree-list-chevron` theme target for the expand/collapse toggle, so consumers can theme the chevron (color, per open/closed state) via `defineTheme` instead of reaching it through the functional `[data-tree-toggle]` attribute. Reflects the open/closed state as a `data-state` attribute (`expanded`/`collapsed`); the functional `data-tree-toggle` hook is unchanged.
+- TreeList: add a stable `astryx-tree-list-guide` theme target on the hierarchy guide (connector) line elements, so consumers can recolor or hide the guides through `defineTheme` (e.g. `backgroundColor`, or `display: 'none'` to hide them) instead of hiding the built-in connectors and reimplementing them with unlayered CSS.
+- TreeList: add a dedicated `astryx-tree-list-item-label` theme target on the item's label text, so consumers can theme just the label (e.g. bold the selected item's label) via `defineTheme` instead of a fragile `button:not([data-tree-toggle]) > span` structural selector. Reflects the row's `selected` state as a `data-selected` attribute on the label.
+
+#### Fixes
+
+- AvatarStatusDot: pair each variant with a distinct built-in shape — success stays a filled dot, neutral renders as a ring, error gets a minus bar — so status no longer relies on colour alone (WCAG 2.1 SC 1.4.1, #4143). A rendered `icon` replaces the shape glyph at sizes where icons fit; themes can target the new stable `astryx-avatar-status-dot-glyph` class and its `data-shape` attribute — a stroked inline `<svg>` painted from the dot's `currentColor`.
+- Button: link-rendered buttons (`href`) now expose `aria-busy` while loading, matching the `<button>` branch. Previously an interruptible loading link showed the spinner and announced "Loading" but carried no machine-readable busy state.
+- Calendar only marks in-month date cells as today, preventing duplicate today indicators in multi-month views.
+- Carousel: slides now expose APG slide semantics (role=group, aria-roledescription="slide", "Slide N of M" labels) instead of anonymous divs.
+- Honor `prefers-reduced-motion` in ChatToolCalls (chevron rotation, expand/collapse), ChatLayoutScrollButton (pill show/hide), and ChatDictationButton (equalizer bars).
+- Chat/useChatStreamScroll: the scroll-follow spring now respects `prefers-reduced-motion` — locked following, `scrollToBottom()`, and `lock()` fall back to the existing instant jump, so the transcript still tracks the bottom without animated travel. Follow-up promised in #3800.
+- Chat: the composer drawer toggle now references its disclosed content via aria-controls, so assistive tech can navigate from the toggle to the drawer.
+- ChatSendButton now forwards `className`, `style`, and pass-through attributes (`data-*`, `aria-*`, and other rest props) to the rendered button. Previously these were silently dropped. (#4190)
+- Chat: tool-call error details are now exposed to screen readers and keyboard users instead of living only in a hover-only title attribute.
+- CheckboxInput: the indeterminate mark now uses the `--radius-full` token instead of a hardcoded radius, for token consistency. No visual change.
+- CheckboxList: items with rich (non-string) labels can now provide an accessibleLabel so their checkbox no longer announces as the literal "Checkbox".
+- CodeBlock: collapsed code regions are now inert, so keyboard focus can no longer land on the invisible scroll container while collapsed.
+- CommandPalette: forward BaseProps pass-through attributes (className, style, xstyle, data-_, aria-_) to the underlying Dialog. Previously these were silently dropped.
+- CommandPalette: the search input (role=combobox) now has an accessible name by default, from the new label prop or the visible placeholder. Previously screen readers announced a nameless combobox.
+- DateTimeInput: ArrowDown (and Alt+ArrowDown) in the date field now opens the calendar popover from the keyboard, matching DateInput and the advertised combobox pattern.
+- Dialog: modals are now automatically labelled by their DialogHeader title via aria-labelledby, matching AlertDialog. Unnamed open dialogs warn in development.
+- Dialog: the entry animation is disabled under prefers-reduced-motion, matching the Layer animation guards.
+- Fix Divider rest-prop spread order so consumer-passed HTML attributes cannot overwrite the component's `role="separator"` or `aria-orientation`.
+- FieldLabel now forwards className, style, xstyle, and pass-through attributes (data-_, aria-_, event handlers) to the rendered element. Previously these were accepted by the type but silently dropped.
+- Field/FieldStatus: status and error messages are now announced through persistent live regions, so they are reliably read by screen readers regardless of when they appear.
+- FileInput: the trigger's accessible name now includes the selected filenames, so screen-reader users can review what is attached when refocusing the control.
+- Prevent PowerSearch edit popover from closing when selecting multi-select options via Enter (#4245)
+- Selector/MultiSelector: PageUp/PageDown now jump the active option to the first/last match while searching, complementing Home/End which stay on text-caret movement.
+- HoverCard: popups now expose a named dialog when the new label prop is set, and honest group semantics otherwise. Previously every hover card announced as an unnamed dialog.
+- Item: aria-selected is now emitted only when the item's role permits it (option, tab, treeitem, grid cells), removing invalid ARIA from plain list items.
+- MobileNav: the toggle button now exposes `aria-expanded` and references the nav drawer via `aria-controls`, so screen-reader users can tell whether the drawer is open and what the button controls. (#3721)
+- MultiSelector: searching within the options popover now announces the number of matching results ("3 results" / "No results found") to screen readers, mirroring Selector and Typeahead. Previously filtering happened silently.
+- SideNav/TopNav: collapsed heading popovers no longer wrap their menus in a modal dialog, and the heading button is no longer an invalid child of the menu.
+- Slider now clamps controlled values to its minimum and maximum before positioning the thumb and exposing ARIA values.
+- Slider: required sliders now convey the required state to screen readers through the thumb's accessible description (aria-required is invalid on the slider role).
+- Make the CLI's `.mjs` sources fully strict-typecheckable (checkJs + JSDoc)
+  Annotated the entire CLI package so `tsconfig.strict.json` (full `strict` `checkJs` over `src`, `bin`, `scripts`, `docs`, and the emitted `templates`) reports zero errors — down from 1717. Fixes are JSDoc-only: no runtime logic changed, `.mjs` stays `.mjs`. Strict checking also surfaced and corrected several type-contract drifts: the `upgrade.run` response type (declared a `depsUpdated` field the command never emits, and omitted the real `integrations`/`filesChanged`/`transformsApplied`/`errors`), registered the emitted `theme.list`/`theme.add`/`layout.*` response types in the `--json` envelope union, and added `category?` to `ReferenceSection` in core's docs types (reference docs already emit it).
+- Table: the selection plugin accepts getRowLabel so row checkboxes announce which row they select, instead of an undifferentiated "Select row".
+- Text: an explicit `size` now overrides the font-size of a themed `type`. The `size` class lived in a lower cascade layer (`astryx-base`) than a theme's per-type font-size rule (`astryx-theme`), so `<Text type="supporting" size="xsm">` silently kept the type's size. Themes now re-emit the size classes in the theme layer so `size` wins as documented.
+- Thumbnail: replace the hover box-shadow on interactive tiles with the same `::after` overlay treatment ClickableCard and SelectableCard use. All three now tint on hover with `--color-overlay-hover` (and `--color-overlay-pressed` on press), so interactive feedback is consistent across the card family.
+- Thumbnail/TopNavMegaMenuFeaturedCard: images without alt text are now explicitly decorative instead of silently empty-alt, matching Avatar's handling.
+- Thumbnail: the overlaid remove button now uses a fixed `--color-overlay` scrim with an `--color-on-dark` icon instead of adapting to the image's luminance, so it has reliable contrast on any image.
+- Tokenizer: adding and removing tokens (including Backspace on an empty input) is now announced to screen readers. Previously tokens appeared and disappeared silently.
+- TopNav: TopNavMegaMenu triggers now expose aria-controls, and the panel is a labeled group instead of an invalid modal-dialog-wrapped menu.
+- TopNav: TopNavMenu popups now expose proper menu semantics (no modal dialog wrapper) with the full APG keyboard pattern (roving tabindex, arrow keys, typeahead).
+
+#### Documentation
+
+- docs(Tokenizer, PowerSearch): document and test the existing startIcon prop
+  Both components have shipped a working `startIcon?: ReactNode | IconType` prop for a while (`PowerSearch` forwards it verbatim to the internal `Tokenizer`, and it's already exercised in Storybook), but neither's `.doc.mjs` documented it and neither had test coverage — so it was invisible to `astryx component <Name> --dense`, the docsite props table, and anyone (human or AI) relying on those as the source of truth. No behavior change; adds the missing props-table entries (en/zh/dense) and colocated tests confirming the icon renders and forwards correctly.
+
+#### Other Changes
+
+- Compact per-row status signal (error, warning, unread, etc.) without a
+  dedicated status column: a colored status dot by default, or an icon when provided.
+- `getStatus(item)` maps a row to `{color, icon?, label?}`, or `null` for no
+  indicator. `color` accepts a semantic status name (`success`/`error`/`warning`/`accent`/`red`/`green`/etc.) mapped to a theme token, or a raw CSS color as an escape hatch.
+- `icon` renders the status as a shape signifier instead of the dot, which is
+  more accessible than color alone when multiple statuses coexist. `label` supplies the accessible name.
+- Memoize `getStatus` with `useCallback` for a stable plugin identity.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @bhamodi
+- @cixzhang
+- @ejc3
+- @freddymeta
+- @HelloOjasMutreja
+- @humbertovirtudes
+- @josephfarina
+- @kentonquatman
+- @Kevinjohn
+- @saadpocalypse
+- @yyq1025
+
+---
+
 # 0.1.8
 
 #### Breaking Changes

package/dist/AppShell/AppShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../src/AppShell/AppShell.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAmBf,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmC5C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7D;;;;;;;GAOG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEhC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC;IAE7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,SAAS,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAkKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAoB,EACpB,MAAM,EACN,QAAQ,EACR,cAAc,EACd,aAAa,EAAE,UAAU,EACzB,MAAe,EACf,SAAS,EACT,OAAO,EACP,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,aAAa,qBAiXf;yBAhYe,QAAQ"}
+{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../src/AppShell/AppShell.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAmBf,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmC5C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7D;;;;;;;GAOG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEhC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC;IAE7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,SAAS,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAkKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAoB,EACpB,MAAM,EACN,QAAQ,EACR,cAAc,EACd,aAAa,EAAE,UAAU,EACzB,MAAe,EACf,SAAS,EACT,OAAO,EACP,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,aAAa,qBAsXf;yBArYe,QAAQ"}

package/dist/AppShell/AppShell.js

@@ -20,7 +20,7 @@ import React from 'react';
  * - /packages/cli/templates/blocks/components/AppShell/ (showcase blocks)
  */
 
-import { isValidElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isValidElement, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, fontWeightVars, radiusVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
@@ -307,15 +307,19 @@ export function AppShell({
   // =========================================================================
   // Mobile context — shared with MobileNavToggle and future TopNav mobile
   // =========================================================================
+  // Stable id shared by the drawer (applied as its `id`) and the toggle
+  // (referenced via `aria-controls`) so screen readers know what it controls.
+  const mobileNavId = useId();
   const mobileContextValue = useMemo(() => ({
     isMobile: isBelowBreakpoint,
     isMobileNavOpen,
+    mobileNavId,
     toggleMobileNav: () => mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
     openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
     closeMobileNav: () => setMobileNavOpen(false),
     isMobileNavEnabled: mobileNavEnabled,
     hasAutoToggle: mobileNavHasToggle
-  }), [isBelowBreakpoint, isMobileNavOpen, setMobileNavOpen, mobileNavEnabled, mobileNavHasToggle]);
+  }), [isBelowBreakpoint, isMobileNavOpen, mobileNavId, setMobileNavOpen, mobileNavEnabled, mobileNavHasToggle]);
 
   // =========================================================================
   // Build header content (topNav + banner)

package/dist/AppShell/AppShellMobileContext.d.ts

@@ -3,6 +3,14 @@ export interface AppShellMobileContextValue {
     isMobile: boolean;
     /** Whether the mobile nav drawer is currently open */
     isMobileNavOpen: boolean;
+    /**
+     * DOM id of the mobile nav drawer. `AppShell` sets this so the toggle can
+     * point its `aria-controls` at the drawer and the drawer can apply it as its
+     * `id`. Optional: callers that construct this context by hand may omit it, in
+     * which case `MobileNav` falls back to a locally generated id and the toggle
+     * simply drops `aria-controls`.
+     */
+    mobileNavId?: string;
     /** Toggle the mobile nav drawer open/closed */
     toggleMobileNav: () => void;
     /** Open the mobile nav drawer */

package/dist/AppShell/AppShellMobileContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShellMobileContext.d.ts","sourceRoot":"","sources":["../../src/AppShell/AppShellMobileContext.tsx"],"names":[],"mappings":"AAiBA,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,eAAe,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,iCAAiC;IACjC,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,kCAAkC;IAClC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,2CAA2C;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC;CACxB;AAYD,eAAO,MAAM,qBAAqB,qDACuB,CAAC;AAG1D;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,0BAA0B,CAE9D"}
+{"version":3,"file":"AppShellMobileContext.d.ts","sourceRoot":"","sources":["../../src/AppShell/AppShellMobileContext.tsx"],"names":[],"mappings":"AAiBA,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,iCAAiC;IACjC,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,kCAAkC;IAClC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,2CAA2C;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC;CACxB;AAYD,eAAO,MAAM,qBAAqB,qDACuB,CAAC;AAG1D;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,0BAA0B,CAE9D"}

package/dist/Avatar/Avatar.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState
+ * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ *   (Tooltip hook) for the optional name-on-hover tooltip
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
  *
@@ -9,15 +10,18 @@
  * - /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.
  *
  * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
  * but the values are larger because avatars align with media rather than
- * glyphs. The tiers match EPS's avatar sizes.
+ * glyphs. The tiers follow the standard avatar size scale.
  */
 type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 /**
@@ -70,6 +74,48 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
      * Typically used for status indicators or badges.
      */
     status?: ReactNode;
+    /**
+     * Tooltip shown on hover (and keyboard focus).
+     * - omitted / `true`: show the avatar's `name`
+     * - a string: show that text instead
+     * - `false`: no tooltip
+     *
+     * The avatar owns this tooltip. It is NOT auto-disabled when wrapped in your
+     * own Tooltip/HoverCard — set `tooltip={false}` if you provide your own
+     * overlay. No tooltip is shown if `tooltip` is `true`/omitted and there is
+     * no (non-whitespace) `name`.
+     * @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.
@@ -82,9 +128,13 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
  * <Avatar src="/user.jpg" name="John Doe" />
  * <Avatar name="Jane Smith" size="xl" />
  * <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, 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;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsC5C;;;;;;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;AAqFD,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;CACpB;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAW,EACX,GAAG,EACH,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwFb;yBArGe,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;AAiJD,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,+BAsOb;yBAzPe,MAAM"}

package/dist/Avatar/Avatar.js

@@ -4,7 +4,8 @@
 
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState
+ * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ *   (Tooltip hook) for the optional name-on-hover tooltip
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
  *
@@ -13,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';
@@ -20,9 +23,11 @@ import "../theme/tokens.stylex.js";
 import { colorVars, typographyVars, fontWeightVars, radiusVars } from "../theme/tokens.stylex.js";
 import { AvatarSizeContext } from "./AvatarSizeContext.js";
 import { useAvatarGroup } from "../AvatarGroup/AvatarGroupContext.js";
-import { mergeProps } from "../utils/index.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°.
  *
@@ -35,7 +40,6 @@ import { themeProps } from "../utils/themeProps.js";
  *
  * This constant represents that ratio: (1 - 1/√2) / 2 ≈ 0.146
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 
 /**
@@ -54,7 +58,7 @@ const INITIALS_FONT_SIZE_RATIO = 0.4;
  *
  * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
  * but the values are larger because avatars align with media rather than
- * glyphs. The tiers match EPS's avatar sizes.
+ * glyphs. The tiers follow the standard avatar size scale.
  */
 
 /**
@@ -95,6 +99,7 @@ const styles = {
     kVAEAm: "x1n2onr6",
     k1xSpc: "x3nfvp2",
     kmuXW: "x2lah0s",
+    kaIpWk: "xjspbzw",
     $$css: true
   },
   content: {
@@ -112,16 +117,39 @@ const styles = {
     kjj79g: "xl56j7k",
     kzqmXN: "xh8yej3",
     kZKoxP: "x5yr21d",
-    kWkggS: "x17x4s8c",
-    kMwMTN: "xv1l7n4",
+    kWkggS: "xelv01g",
+    kMwMTN: "xicfil",
     kMv6JI: "x9ynric",
-    k63SB2: "x1e4wzip",
+    k63SB2: "xi08x9w",
     kP9fke: "xtvhhri",
     $$css: true
   },
   status: {
     kVAEAm: "x10l6tqk",
     $$css: true
+  },
+  focusable: {
+    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
   }
 };
 
@@ -148,7 +176,7 @@ const dynamicStyles = {
     "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(size)
   }],
   fontSize: size => [_temp, {
-    "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(size * INITIALS_FONT_SIZE_RATIO)
+    "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(`var(--_avatar-fallback-font-size, ${size * INITIALS_FONT_SIZE_RATIO}px)`)
   }],
   statusPosition: size => [_temp2, {
     "--x-bottom": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(size * CIRCLE_EDGE_OFFSET_RATIO),
@@ -229,6 +257,10 @@ function DefaultIcon({
  * <Avatar src="/user.jpg" name="John Doe" />
  * <Avatar name="Jane Smith" size="xl" />
  * <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({
@@ -239,6 +271,12 @@ export function Avatar({
   size = 'md',
   src,
   status,
+  tooltip = true,
+  href,
+  as,
+  target,
+  rel,
+  onClick,
   xstyle,
   className,
   style,
@@ -262,50 +300,166 @@ export function Avatar({
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
-  return /*#__PURE__*/_jsx(AvatarSizeContext, {
-    value: numericSize,
-    children: /*#__PURE__*/_jsxs("div", {
+
+  // Resolve the tooltip content:
+  // - `false`            → no tooltip
+  // - a string           → that string
+  // - `true` / omitted   → the `name` (a whitespace-only name yields nothing)
+  // Note: the *visible* tooltip prefers `name` (not `alt`); the *accessible
+  // name* on the root still uses `alt || name` above, independent of this.
+  const tooltipContent = tooltip === false ? undefined : typeof tooltip === 'string' ? tooltip : name;
+  const trimmedTooltip = tooltipContent?.trim();
+  const showTooltip = trimmedTooltip != null && trimmedTooltip !== '';
+  // Whether the tooltip text is a consumer-authored override (a custom string)
+  // rather than the default name. A custom description is worth wiring to
+  // `aria-describedby` (it adds information, matching Button); the default name
+  // tooltip is visual-only — its text duplicates the root `aria-label`, so
+  // describing it too would double-announce the same name (OQ-4).
+  const isCustomTooltip = typeof tooltip === 'string';
+
+  // Own the name tooltip via the Tooltip hook (the Button pattern), which
+  // 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 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;
+
+  // 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 xelv01g xicfil x9ynric xi08x9w 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: ref,
+      ref: rootRef,
       role: isDecorative ? 'presentation' : 'img',
       "aria-label": isDecorative ? undefined : accessibleName,
-      "aria-hidden": isDecorative || undefined,
+      "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. Suppressed inside
+      // an AvatarGroup, which owns a single roving tab stop for its members.
+      ,
+      tabIndex: showTooltip && !avatarGroup ? 0 : undefined,
       "data-testid": testId,
-      ...mergeProps(themeProps('avatar', {
-        size: resolvedSize
-      }), stylex.props(styles.wrapper, 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
-      })]
-    })
+      ...describedByProp,
+      ...rootStylexProps,
+      children: visualContent
+    });
+  }
+  const avatarElement = /*#__PURE__*/_jsx(AvatarSizeContext, {
+    value: numericSize,
+    children: rootElement
+  });
+
+  // Always return the same structure so the avatar keeps its position in the
+  // React tree regardless of the tooltip flag — toggling it must not remount
+  // the avatar subtree (and lose image-load state). The tooltip is a sibling
+  // (no wrapper DOM); the hook's ref is already on the root via `rootRef`.
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [avatarElement, showTooltip ? tooltipHook.renderTooltip(trimmedTooltip) : null]
   });
 }
 Avatar.displayName = 'Avatar';