@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/dist/utils/rtlStyles.js

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rtlStyles.ts
+ * @input None
+ * @output Shared StyleX style that horizontally mirrors an element under RTL
+ * @position Core utility; applied to directional-icon wrappers in Calendar,
+ *   Lightbox, and the Table expand/disclosure plugins
+ *
+ * `mirror` flips its element on the horizontal axis only when an ancestor
+ * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
+ * vertical axis intact, and applying it OUTSIDE any state-driven rotation lets
+ * it compose correctly — e.g. a Table disclosure chevron still rotates to point
+ * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
+ * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/index.ts
+ */
+
+import * as stylex from '@stylexjs/stylex';
+export const rtlStyles = {
+  mirror: {
+    k3aq6I: "xgtlewx",
+    $$css: true
+  }
+};

package/locales/en.json

@@ -235,10 +235,22 @@
     "defaultMessage": "Mobile navigation",
     "description": "Screen-reader-only accessible name for the mobile-only navigation region on small viewports. \"Mobile\" = phone/tablet (small screen), not \"movable\"."
   },
+  "@astryx.avatar.nameWithStatus": {
+    "defaultMessage": "{name}, {status}",
+    "description": "Screen-reader accessible name for an Avatar showing a status indicator; composes the person's name with the status label, e.g. \"Jane Doe, Online\". {name} = the avatar's name/alt text, {status} = the status dot's label. Adjust separator and order per locale."
+  },
   "@astryx.avatarGroup.label": {
     "defaultMessage": "Avatars",
     "description": "Screen-reader-only fallback name for a horizontal cluster of user avatar images. Plural noun; consumers usually override with \"Team members\", \"Attendees\", etc."
   },
+  "@astryx.avatarGroup.keyboardHint": {
+    "defaultMessage": "Use arrow keys to move between avatars",
+    "description": "Screen-reader-only instruction attached (via aria-describedby) to a group of interactive avatars that share a single Tab stop. Tells keyboard users the Left/Right arrow keys move focus between the avatars. Only announced when the group has interactive (link/button) avatars."
+  },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "{count, number} more",
+    "description": "Accessible name for the \"+N\" overflow indicator at the end of an AvatarGroup — announces how many additional avatars are not shown. Example: `5 more`. The visible \"+N\" text is unaffected; this is the aria-label only."
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "Dismiss",
     "description": "\"Dismiss\" = close/hide this notification (not \"reject a person\"). Aria label AND tooltip on the small X button on a Banner."
@@ -251,6 +263,34 @@
     "defaultMessage": "Next month",
     "description": "Screen-reader-only label on the right-arrow button in a Calendar's month header (navigates one month forward). Pairs with `calendar.previousMonth`."
   },
+  "@astryx.calendar.daySelected": {
+    "defaultMessage": "{date}, selected",
+    "description": "Accessible name for the Calendar day button that is the current single-mode selection. `{date}` is the localized full date, e.g. \"Thursday, January 15, 2026\". The trailing state word tells screen-reader users the focused day is selected."
+  },
+  "@astryx.calendar.dayRangeStart": {
+    "defaultMessage": "{date}, range start",
+    "description": "Accessible name for the Calendar day button that begins the selected date range (or the first pick of an in-progress range). `{date}` is the localized full date."
+  },
+  "@astryx.calendar.dayRangeEnd": {
+    "defaultMessage": "{date}, range end",
+    "description": "Accessible name for the Calendar day button that ends the selected date range. `{date}` is the localized full date. Pairs with `calendar.dayRangeStart`."
+  },
+  "@astryx.calendar.dayRangeStartAndEnd": {
+    "defaultMessage": "{date}, range start and range end",
+    "description": "Accessible name for a Calendar day button that both begins and ends a completed one-day range. `{date}` is the localized full date."
+  },
+  "@astryx.calendar.dayInRange": {
+    "defaultMessage": "{date}, in range",
+    "description": "Accessible name for a Calendar day button strictly inside the selected date range (not an endpoint). `{date}` is the localized full date."
+  },
+  "@astryx.calendar.rangeStartAnnounce": {
+    "defaultMessage": "Start date {date}. Select an end date.",
+    "description": "Screen-reader announcement after the first pick of a Calendar range selection. `{date}` is the localized full date. Prompts the user that a second pick completes the range."
+  },
+  "@astryx.calendar.rangeCompleteAnnounce": {
+    "defaultMessage": "Selected range: {start} to {end}.",
+    "description": "Screen-reader announcement after the second pick completes a Calendar range selection. `{start}` and `{end}` are localized full dates in chronological order."
+  },
   "@astryx.carousel.label": {
     "defaultMessage": "Carousel",
     "description": "Screen-reader-only fallback name for a horizontally-scrolling row of items. If \"carousel\" is unfamiliar in your locale, prefer the standard term (e.g. \"slider\")."
@@ -307,6 +347,18 @@
     "defaultMessage": "Type to search",
     "description": "Onboarding empty-state text shown inside a CommandPalette on first open, before the user has typed anything. Imperative sentence fragment."
   },
+  "@astryx.commandPalette.resultCount": {
+    "defaultMessage": "{count, number} {count, plural, one {result} other {results}}",
+    "description": "Screen-reader-only announcement of how many commands match the CommandPalette query as the user types. Example: `12 results`, `1 result`; keep compact."
+  },
+  "@astryx.commandPalette.noResultsFor": {
+    "defaultMessage": "No results for {query}",
+    "description": "Screen-reader-only announcement when a CommandPalette query matches nothing. `{query}` is the user's verbatim search text; keep it last if your language allows so truncation-by-AT still conveys the outcome."
+  },
+  "@astryx.commandPalette.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only announcement that a CommandPalette search has started and results are being fetched. Present-progressive form; matches the visible spinner."
+  },
   "@astryx.dateRangeInput.presetDateRanges": {
     "defaultMessage": "Preset date ranges",
     "description": "Screen-reader-only accessible name for the sidebar of quick-pick preset ranges inside a DateRangeInput popover (e.g. \"Last 7 days\", \"This month\")."
@@ -359,6 +411,10 @@
     "defaultMessage": "Search options",
     "description": "Screen-reader-only accessible name for that same search input inside a MultiSelector."
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "{label}, partially selected",
+    "description": "Accessible name for the MultiSelector select-all option while only some options are selected. `{label}` is the visible select-all label (e.g. \"Select all\"). ARIA forbids aria-selected=\"mixed\" on options, so the indeterminate state is conveyed through the name instead. \"Partially\" = some but not all."
+  },
   "@astryx.popover.close": {
     "defaultMessage": "Close popover",
     "description": "\"Close\" = shut/dismiss, not \"nearby\". Screen-reader-only label on the close button inside a Popover."
@@ -635,6 +691,10 @@
     "defaultMessage": "Expand",
     "description": "\"Expand\" = reveal more, not grow physically. Aria label AND tooltip on the same toggle when currently collapsed. Pairs with `banner.collapse`."
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense (\"work in progress\"), not a noun. Kept separate from `typeahead.loading` — translations may diverge."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."
@@ -643,6 +703,14 @@
     "defaultMessage": "Collapse {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is expanded. Example: `Collapse Attachments`. Pairs with `expand`."
   },
+  "@astryx.chatDictationButton.startDictation": {
+    "defaultMessage": "Start dictation",
+    "description": "Accessible label for the microphone button when idle (not listening)."
+  },
+  "@astryx.chatDictationButton.stopDictation": {
+    "defaultMessage": "Stop dictation",
+    "description": "Accessible label for the microphone button when actively listening."
+  },
   "@astryx.chatLayout.newMessages": {
     "defaultMessage": "New messages",
     "description": "Text on a floating pill at the bottom of a chat viewport when unseen messages arrive below the fold; clicking scrolls to bottom. Keep short — narrow pill."
@@ -663,6 +731,14 @@
     "defaultMessage": "Send",
     "description": "Primary button label on the chat submit button (paperplane icon). Imperative verb; pairs with `Stop`. Very short."
   },
+  "@astryx.chatToolCalls.error": {
+    "defaultMessage": "Error: {message}",
+    "description": "Screen-reader text for a tool call that failed. {message} is the error detail."
+  },
+  "@astryx.chatToolCalls.groupLabel": {
+    "defaultMessage": "{count} tool calls",
+    "description": "Summary label shown in the group header when multiple tool calls are expanded. {count} is the number of calls."
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "Suggestions",
     "description": "Screen-reader-only fallback label for the popover listbox opened by a trigger character (`@`, `/`) in the chat composer when the trigger provides no specific label."
@@ -683,18 +759,42 @@
     "defaultMessage": "Code",
     "description": "Screen-reader-only fallback name for a code-snippet scroll container when the code's language is unknown. \"Code\" = source code, not secret code or code of conduct."
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "Optional",
+    "description": "Visible indicator shown next to a form field's label when the field is optional (isOptional). Mutually exclusive with the required indicator. Very short — appears inline after the label text."
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "Required",
+    "description": "Visible indicator shown next to a form field's label when the field must be filled in (isRequired). Mutually exclusive with the optional indicator. Very short — appears inline after the label text."
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that removes the selected file from a FileInput. Example: `Clear Attachment`, `Clear Résumé`."
   },
+  "@astryx.fileInput.required": {
+    "defaultMessage": "Required",
+    "description": "Screen-reader-only description on the FileInput trigger indicating the field must be filled in. Mirrors the visible `Required` indicator next to the field label; conveyed via description because aria-required is not supported on role=\"button\"."
+  },
   "@astryx.fileInput.triggerWithFiles": {
     "defaultMessage": "{label}, {fileNames}",
     "description": "Accessible name for a FileInput trigger that has files attached, composing the field label with the selected filenames. Example: `Attachments, report.pdf, notes.txt`."
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "to navigate",
+    "description": "Trailing text in the keyboard-hint badge, shown after arrow-key icons — reads as `← → to navigate`. Lowercase sentence fragment completing the visual phrase; the badge is aria-hidden, so this is for sighted users only."
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "Media viewer",
     "description": "Screen-reader-only fallback name for the Lightbox dialog when the current media item has no alt text. Should rarely render — consumers should provide alt."
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "Show more",
+    "description": "Button label under a MetadataList that reveals items hidden beyond the configured maximum. Toggles with `metadataList.showLess` — keep the pair parallel in your language."
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "Show less",
+    "description": "Button label under a MetadataList that re-hides the extra items revealed by `metadataList.showMore`. Keep the pair parallel."
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "Navigation",
     "description": "Screen-reader-only fallback name for the MobileNav overlay dialog when no explicit label was passed."
@@ -703,6 +803,18 @@
     "defaultMessage": "Clear all {label}",
     "description": "Screen-reader-only label on the X that clears every selected value from a MultiSelector. Example: `Clear all Countries`. `{label}` is typically already plural in English."
   },
+  "@astryx.input.statusButton.error": {
+    "defaultMessage": "Error details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is error. Activating or focusing the button reveals the error message in a tooltip. Keep it short — it labels an icon-only button."
+  },
+  "@astryx.input.statusButton.warning": {
+    "defaultMessage": "Warning details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is warning. Activating or focusing the button reveals the warning message in a tooltip."
+  },
+  "@astryx.input.statusButton.success": {
+    "defaultMessage": "Success details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is success. Activating or focusing the button reveals the success message in a tooltip."
+  },
   "@astryx.numberInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a NumberInput. Example: `Clear Age`, `Clear Quantity`."

package/locales/pseudo.json

@@ -176,9 +176,18 @@
   "@astryx.appShell.mobileNavigation": {
     "defaultMessage": "⟦Ṁóƀíłé ñàṽíĝàţíóñ⟧"
   },
+  "@astryx.avatar.nameWithStatus": {
+    "defaultMessage": "⟦{name}, {status}⟧"
+  },
   "@astryx.avatarGroup.label": {
     "defaultMessage": "⟦Àṽàţàřš⟧"
   },
+  "@astryx.avatarGroup.keyboardHint": {
+    "defaultMessage": "⟦Úšé àřřóŵ ķéýš ţó ɱóṽé ƀéţŵééñ àṽàţàřš⟧"
+  },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "⟦{count, number} ɱóřé⟧"
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "⟦Ðíšɱíšš⟧"
   },
@@ -188,6 +197,27 @@
   "@astryx.calendar.nextMonth": {
     "defaultMessage": "⟦Ñéẋţ ɱóñţĥ⟧"
   },
+  "@astryx.calendar.daySelected": {
+    "defaultMessage": "⟦{date}, šéłéçţéð⟧"
+  },
+  "@astryx.calendar.dayRangeStart": {
+    "defaultMessage": "⟦{date}, řàñĝé šţàřţ⟧"
+  },
+  "@astryx.calendar.dayRangeEnd": {
+    "defaultMessage": "⟦{date}, řàñĝé éñð⟧"
+  },
+  "@astryx.calendar.dayRangeStartAndEnd": {
+    "defaultMessage": "⟦{date}, řàñĝé šţàřţ àñð řàñĝé éñð⟧"
+  },
+  "@astryx.calendar.dayInRange": {
+    "defaultMessage": "⟦{date}, íñ řàñĝé⟧"
+  },
+  "@astryx.calendar.rangeStartAnnounce": {
+    "defaultMessage": "⟦Šţàřţ ðàţé {date}. Šéłéçţ àñ éñð ðàţé.⟧"
+  },
+  "@astryx.calendar.rangeCompleteAnnounce": {
+    "defaultMessage": "⟦Šéłéçţéð řàñĝé: {start} ţó {end}.⟧"
+  },
   "@astryx.carousel.label": {
     "defaultMessage": "⟦Çàřóúšéł⟧"
   },
@@ -230,6 +260,15 @@
   "@astryx.commandPalette.emptyBootstrap": {
     "defaultMessage": "⟦Ţýþé ţó šéàřçĥ⟧"
   },
+  "@astryx.commandPalette.resultCount": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {result} other {results}}⟧"
+  },
+  "@astryx.commandPalette.noResultsFor": {
+    "defaultMessage": "⟦Ñó řéšúłţš ƒóř {query}⟧"
+  },
+  "@astryx.commandPalette.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.dateRangeInput.presetDateRanges": {
     "defaultMessage": "⟦Þřéšéţ ðàţé řàñĝéš⟧"
   },
@@ -269,6 +308,9 @@
   "@astryx.multiSelector.searchOptions": {
     "defaultMessage": "⟦Šéàřçĥ óþţíóñš⟧"
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "⟦{label}, þàřţíàłłý šéłéçţéð⟧"
+  },
   "@astryx.popover.close": {
     "defaultMessage": "⟦Çłóšé þóþóṽéř⟧"
   },
@@ -476,12 +518,21 @@
   "@astryx.banner.expand": {
     "defaultMessage": "⟦Éẋþàñð⟧"
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },
   "@astryx.chatComposerDrawer.collapse": {
     "defaultMessage": "⟦Çółłàþšé {label}⟧"
   },
+  "@astryx.chatDictationButton.startDictation": {
+    "defaultMessage": "⟦Šţàřţ ðíçţàţíóñ⟧"
+  },
+  "@astryx.chatDictationButton.stopDictation": {
+    "defaultMessage": "⟦Šţóþ ðíçţàţíóñ⟧"
+  },
   "@astryx.chatLayout.newMessages": {
     "defaultMessage": "⟦Ñéŵ ɱéššàĝéš⟧"
   },
@@ -497,6 +548,12 @@
   "@astryx.chatSendButton.send": {
     "defaultMessage": "⟦Šéñð⟧"
   },
+  "@astryx.chatToolCalls.error": {
+    "defaultMessage": "⟦Éřřóř: {message}⟧"
+  },
+  "@astryx.chatToolCalls.groupLabel": {
+    "defaultMessage": "⟦{count} ţóół çàłłš⟧"
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "⟦Šúĝĝéšţíóñš⟧"
   },
@@ -512,21 +569,48 @@
   "@astryx.codeBlock.code": {
     "defaultMessage": "⟦Çóðé⟧"
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "⟦Óþţíóñàł⟧"
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "⟦Řéɋúířéð⟧"
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.fileInput.required": {
+    "defaultMessage": "⟦Řéɋúířéð⟧"
+  },
   "@astryx.fileInput.triggerWithFiles": {
     "defaultMessage": "⟦{label}, {fileNames}⟧"
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "⟦ţó ñàṽíĝàţé⟧"
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "⟦Ṁéðíà ṽíéŵéř⟧"
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "⟦Šĥóŵ ɱóřé⟧"
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "⟦Šĥóŵ łéšš⟧"
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "⟦Ñàṽíĝàţíóñ⟧"
   },
   "@astryx.multiSelector.clearAll": {
     "defaultMessage": "⟦Çłéàř àłł {label}⟧"
   },
+  "@astryx.input.statusButton.error": {
+    "defaultMessage": "⟦Éřřóř ðéţàíłš⟧"
+  },
+  "@astryx.input.statusButton.warning": {
+    "defaultMessage": "⟦Ŵàřñíñĝ ðéţàíłš⟧"
+  },
+  "@astryx.input.statusButton.success": {
+    "defaultMessage": "⟦Šúççéšš ðéţàíłš⟧"
+  },
   "@astryx.numberInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.9",
+  "version": "0.2.0-canary.136a00f",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -54,6 +54,11 @@
       "types": "./src/tailwind-theme.css.d.ts",
       "default": "./src/tailwind-theme.css"
     },
+    "./BaseProps": {
+      "source": "./src/BaseProps.ts",
+      "types": "./dist/BaseProps.d.ts",
+      "default": "./dist/BaseProps.js"
+    },
     "./naming": {
       "source": "./src/naming.ts",
       "types": "./dist/naming.d.ts",

package/src/Avatar/Avatar.doc.mjs

@@ -32,6 +32,18 @@ export const docs = {
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
       {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
+    vars: [
+      {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},
+      {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},
+      {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},
+      {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},
+    ],
+    derived: [
+      {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
+      {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
+      {property: 'color', vars: ['--_avatar-fallback-color']},
+      {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
+    ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
   props: [
@@ -64,7 +76,7 @@ export const docs = {
     {
       name: 'status',
       type: 'ReactNode',
-      description: 'Corner content for status indicators.',
+      description: 'Corner content for status indicators. A string `label` on the element (as on AvatarStatusDot) is composed into the avatar\'s accessible name (e.g. "Jane Doe, Online") so screen readers announce the status.',
       slotElements: [
         {
           __element: 'AvatarStatusDot',
@@ -79,9 +91,37 @@ export const docs = {
       name: 'tooltip',
       type: 'string | boolean',
       description:
-        "Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard — set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name.",
+        "Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard. Set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name.",
       default: 'true',
     },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When set, the avatar renders as an interactive link (`<a>` or a custom link component) pointing here. This follows the same element-swap rule as Button. Requires a meaningful accessible name via `alt` or `name`. Inside an AvatarGroup, interactive avatars share a single Tab stop and are reached with arrow keys.',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description:
+        'Custom link component used when `href` is set (e.g. Next.js `Link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description: 'Link target attribute. Only applies with `href`.',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description: 'Link rel attribute. Only applies with `href`.',
+    },
+    {
+      name: 'onClick',
+      type: '(e: MouseEvent) => void',
+      description:
+        'Click handler. When set without `href`, the avatar renders as a focusable `<button type="button">`. Requires a meaningful accessible name via `alt` or `name`.',
+    },
   ],
   components: [
     {name: 'AvatarStatusDot'},
@@ -112,6 +152,7 @@ export const docsDense = {
       {guidance: true, description: 'Always pass a name for initials fallback and screen reader alt text.'},
       {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
+      {guidance: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
       {guidance: false, description: 'Use for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],
@@ -122,9 +163,15 @@ export const docsDense = {
     name: 'user name for initials and alt text',
     alt: 'alt text; falls back to name',
     size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
-    status: 'corner content for status indicators',
+    status:
+      'corner content for status indicators; its `label` is composed into the avatar accessible name ("Jane Doe, Online")',
     tooltip:
       "hover/focus tooltip. true/omitted → name; string → that text; false → none. Owns its tooltip; set false when wrapping in your own Tooltip/HoverCard. Default true.",
+    href: 'renders avatar as a link (<a>/custom). Needs alt/name. Button-style element swap.',
+    as: 'custom link component for href (e.g. Next Link). Only with href.',
+    target: 'link target. Only with href.',
+    rel: 'link rel. Only with href.',
+    onClick: 'click handler → renders <button> when no href. Needs alt/name.',
   },
   components: [
     {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},