@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @xds/core
 
+# 0.4.6
+
+#### New Features
+
+- DateInput fits the pointer: a touch picker on a finger, the text field
+  on a mouse (#5243)
+
+  `DateInput` has always been a control for a mouse — a field you type into with a calendar in a popover beside it. On a phone or a tablet that is the wrong shape: the popover is a desktop calendar operated by thumb, and focusing the field summons a keyboard that covers the thing it is meant to fill in.
+
+  The same component now renders a second surface where the primary pointer is a finger (`pointer: coarse`): a bottom sheet holding one month per screen, swiped sideways, with month and year wheels behind the header title for the far jumps swiping is bad at, arrows in the header corner for a single step, and every target floored at 44px. A day commits the moment it is tapped and leaves the sheet up, so a mistake can be corrected in place; Save closes the picker, and Reset puts it back to how it opened — no date, current month. The grid spills adjacent-month days, muted and unselectable, and the weekday header is three letters rather than two, both as the desktop calendar has them.
+
+  The month and year wheels are one layer that fades in and out on top of the calendar. The calendar itself never fades — it is covered and uncovered, so the only thing moving is the thing arriving. The layer carries an opaque background of its own, which is what makes the fade uniform: it renders as a finished image and the fade applies to the image, rather than the wheels' translucent selection band compositing against a live grid on its own terms.
+
+  Nothing changes at the call site. It is one component with two surfaces, not two components — same props, same values, no new import, no media query to write. Existing usage is untouched: with a mouse the rendered output is the control that was always there.
+
+  The switch is the pointer alone, deliberately with no width bound. `pointer` means the PRIMARY device, so a touchscreen laptop reports `fine` and keeps the typable field (its keyboard is right there), while a narrowed desktop window is still a mouse. Adding a width test would only re-exclude tablets, which are the clearest case for a thumb picker.
+
+  The public surface barely moves: six `@astryx.dateInput.*` catalog keys for the picker's header and footer, and nothing else. No new props, no new exports — `DateInputProps` is byte-identical at 25.
+
+  Nothing else is published, on purpose. There is no export that forces a surface: the touch picker is reachable by being on a touch device, which is the only place it is worth looking at. The media query the switch runs on is an internal constant, not an export — six other core components write `@media (pointer: coarse)` inline rather than sharing one, and nothing has asked to ask the same question. The picker's two sizes (the 44px day cell, the 28px wheel row) are compile-time constants rather than theme variables — the day size is an accessibility floor, and a variable a theme can quietly lower is not a floor. And the sheet's header button is addressed by a `data-` attribute rather than a theme target, because nothing has asked to restyle it. Each of those is additive later and awkward to withdraw once shipped.
+
+  The wheels also answer a mouse now. A wheel is a scroll container, so a finger pans it for free; a mouse got nothing, because browsers do not drag-scroll an overflow container — pressing and pulling on the one control shaped like a thing you spin did nothing at all. Dragging with a mouse works, and fixes a related bug on the way: BottomSheet begins its own drag from a `pointerdown` on its body and captures the pointer for it, so a click on a wheel row that wobbled more than a pixel or two used to select nothing.
+- Export `useLocale` and `useCollator` for provider-backed formatting and comparison (#5194)
+- RadioListItem: the `radio-list-item` row theme target now carries `size`, `selected`, and `disabled` state variants (matching `multi-selector-option`), so themes can style selected or disabled rows (#5143).
+- RadioListItem: the `radio-list-item` theme target now rides the painting row element (converging with `list-item`), so a theme can style the row's hover background, padding, and border radius — previously it sat on a layout-only wrapper that painted nothing. The default (unthemed) row appearance is unchanged: it stays a bare surface with no row padding, radius, or hover/selected background (only the radio indicator tints on hover) (#5143).
+- `Section`, `Stack` (with `HStack` / `VStack`) and `Center` accept a padding prop for each of the four edges — `paddingBlockStart`, `paddingBlockEnd`, `paddingInlineStart` and `paddingInlineEnd` — so an edge can take its own spacing step without an `xstyle` escape hatch. `Section` also gains the `paddingInline` axis prop it was missing, so all three components now expose the same seven-prop set (#5224).
+  Each prop takes the same spacing scale as `padding`, and resolution is most-specific-wins, per edge:
+
+  > edge prop → axis prop (`paddingInline` / `paddingBlock`) → `padding`
+
+  An edge prop changes its own edge and leaves the other three alone.
+
+  ```tsx
+  <Section padding={6} paddingBlockStart={2}>…</Section>   // tight top, 24px elsewhere
+  <Stack padding={4} paddingInlineEnd={0}>…</Stack>         // flush trailing edge
+  ```
+
+  The inline props are logical, so `paddingInlineStart` is the left edge in LTR and the right edge in RTL.
+
+  On `Section` the matching `--container-padding-*` custom property moves with the prop, so bleed children (`Table`, `Divider`, a nested `Section`) keep compensating against the padding actually applied.
+
+  Existing code is unaffected: `padding`, `paddingInline` and `paddingBlock` behave exactly as before, and their generated class output is unchanged.
+- Selector: add the `selector-option-row` theme target on the dropdown option row, carrying `size` plus `selected`/`disabled` state — so a theme can restyle row padding and density directly (mirroring `multi-selector-option`), instead of reaching the bare `role="option"` element with a structural selector (#5179).
+- MediaTheme: add `mode="auto"` and `mode="off"` (#5299)
+  A theme is free to define `--color-background-inverted` as something that is not inverted — and a component that hardcodes `mode="dark"` then paints white text on pale grey at 1.25:1. The surface color is a runtime value and the mode was a compile-time guess, so no amount of care in the component could catch it.
+
+  `mode="auto"` measures the surface the browser actually painted and applies whichever of the theme's own `--color-on-dark` / `--color-on-light` reads better on it. There is no threshold and no contrast target: it picks between the theme's two answers, so a theme that wants a soft pairing still gets one. Deciding a surface needs _no_ media context stays an authoring choice — that is the new `mode="off"`, which renders the same element without the media attribute so children never remount.
+
+  When the backdrop is not knowable from CSS — during SSR, on the first client frame, and most often behind a `background-image`, whose pixels need sampling (see `useImageMode`) rather than a computed style — `auto` uses the new `fallback` prop instead of guessing.
+
+  Toast now uses `mode="auto"`, with its previous rule kept only as that fallback. Every stock Astryx surface renders exactly as before.
+- Tooltip and HoverCard: tap to open where there is no hover (#5248)
+  Hover is the one trigger a touch screen cannot express, and both components were answering that badly. `Tooltip` suppressed itself on any device reporting `(hover: none)`, so its content — often the only label an icon button has — was simply unreachable on a phone. `HoverCard` did nothing at all: the `mouseenter` a tap synthesizes opened the card on every tap of its trigger, over the control the user was aiming at, with no gesture that closed it again.
+
+  Both now take a `touchTrigger` prop, and what the trigger DOES decides the default. A trigger that performs an action — a button, a link, a form control — keeps its tap under `auto`: the layer stays shut, because the tap already has somewhere to go and a hint about a control the user just operated is noise. A trigger that performs no action — an info icon, an abbreviation, a truncated label — has nothing to lose, so the tap opens the layer, with no show delay (a tap is a decision, not the hover intent the delay exists to filter) and a tap outside to dismiss it. `tap` and `none` state the choice outright; `tap` is what an info icon rendered as a button wants, since it looks like an action to the DOM while revealing the layer is the only thing it does.
+
+  Hover-capable devices are unaffected, hybrid ones included: the decision is made per interaction from the pointer type rather than once per device from a media query, so the same trigger opens on hover under a mouse and on tap under a finger. A stylus is a hover device by the same rule — a pen in detection range fires hover events with nothing in contact, so it opens the layer on hover, and only a pen that lands counts as a tap. Neither layer opens from the focus a tap leaves behind any more — the second way a tap could bury the control it activated, and on `Tooltip` it is the tapped text fields that were affected, since those match `:focus-visible` by design.
+
+  [fix] InfoTip (lab): opts into `touchTrigger="tap"`. Its trigger is a real button, so the `auto` rule would hand the tap to the control — but revealing the tooltip is that button's only purpose, and suppressing it left an InfoTip's content unreachable on a phone.
+
+#### Fixes
+
+- Avatar: a status element now reports its own accessible label to the avatar through context, so wrapping `AvatarStatusDot` in a component of your own keeps the status in the avatar's accessible name ("Jane Doe, Online") instead of silently dropping it — the `role="img"` root prunes descendant semantics, so composing it in is the only route to assistive tech (WCAG 4.1.2). Reading `label` off a directly-passed element still works and still resolves on the first render. An interactive avatar (`href`/`onClick`) with no `name`/`alt` warns in development, and a status label no longer counts as the control's identity: "Online" reads as a legitimate name while saying nothing about where the link goes. Derived `role`/`aria-label`/`aria-hidden` now spread before the passthrough props, following Icon, so a consumer's own values win. No API change (#5034)
+- AvatarGroup: four defects out of the component audit, three of them in `AvatarGroupOverflow` (#5055).
+  The indicator was `display: flex` on a span, which is a block-level flex container, so the exported component rendered as a full-width bar instead of a circle anywhere outside an `AvatarGroup`: measured 1168px wide in a 1168px parent. It is `inline-flex` now; inside a group nothing changes, because a flex item is blockified either way.
+
+  Its label font size was a bare `size * 0.35`, which computes 7px at `xsm` and 8.4px at `sm`. That is under the 12px legibility floor, and the effect is worse than the number suggests: the glyph stroke ends up thinner than a pixel, so it never reaches its own text colour. Decoded from a screenshot, the darkest pixel at `xsm` is `#bebebe` on a `#f0f0f0` field, a contrast of 1.63:1 where 4.5:1 is required. The size now floors at the `--text-supporting-size` role token and scales proportionally above it, so `md` and larger are unchanged.
+
+  The indicator also kept its negative overlap margin when it was the first child of a group, hanging 12px outside the group's own box. It now carries the same `:not(:first-child)` guard `Avatar` already had. And a negative `count` rendered the string `+-3` and announced "-3 more"; since the documented shape for the prop is `total - visibleCount`, which goes negative whenever the list is shorter than the slice, it now clamps at zero.
+
+  Docs: the guidance told readers to "set max to limit visible avatars", and there is no `max` prop. The API is compositional on purpose, so the consumer slices; the guidance now says that. The keyboard behaviour names the APG roving tabindex technique it implements, and `size` now says that the group's value wins over each child avatar's own `size`, including when the group leaves it at the default.
+- Blockquote: the `cite` attribution renders as a bare `<cite>` instead of being wrapped in a `<footer>`, which was becoming a `contentinfo` document landmark. Also guards the slot with `isRenderable`, so `cite={condition && author}` no longer emits an empty `<cite>`, and wraps long unbroken words instead of overflowing (#5144).
+- Bottom Sheet: float the grab handle so content sits closer to the top (#5222)
+  The drag area above the sheet's content was a 48px row in the sheet's flex column, pushing everything below it down by its full height and reading as an empty band above the first line of content.
+
+  The bar is now 24px and floats over the content: the scrolling area starts at the sheet's top edge and rides up under the pill, so a heading sits 24px closer to the top. The pill is 4px tall centered in the band, so it occupies only 10-14px from the edge — inside the top padding a content wrapper already provides — and a surface gradient behind it keeps it legible over whatever sits or scrolls beneath.
+- BottomSheet: give the sheet one uniform edge against the scrim. Two things were wrong in dark mode. The sheet drew no edge of its own — surface and scrim sit a few RGB steps apart and the `--shadow-high` drop shadow is black on near-black, so the left and right edges were invisible (measured 1.16:1 boundary contrast in dark against 2.89:1 in light); it now carries a `--border-width` / `--color-border` hairline on its three scrim-facing edges, the same treatment MobileNav gives its scrim-facing edge. And under a theme that packs an inset ring into `--shadow-high` (every bundled theme adds one in dark mode) that ring was painted over by an opaque content wrapper such as `Section`, so it showed only in the gap below where the content ended and the side edges appeared to change width partway down; the scrolling body now paints the surface across the sheet's whole inner box, hiding the ring evenly (#5305).
+- Breadcrumbs: button crumbs keep the link's vertical padding, the variant reaches the item theme targets, and interactive crumbs paint the shared focus ring (#5332)
+- DateInput's touch calendar no longer rests between two months (#5319)
+  Swiping the month calendar on iOS could leave it parked a couple of columns into a pane: the left of March and the right of April on screen at once, under one square Sun-to-Sat header, with the title still naming March. The grid was never skewed — the scrollport was simply at rest where no month begins.
+
+  `scroll-snap-type: mandatory` is supposed to make that impossible, and on a static list it does. This list is virtualized: seven panes exist out of twelve hundred, and the panes ARE the snap areas, so every month the finger crosses mounts one and unmounts another while the fling is still running. iOS scrolls off the main thread — it picks a landing place from the snap points it knows about at that moment, and a React re-render that lands after the decision moves them. The scroller stops where a snap point used to be and nothing re-snaps it. Chrome never showed it because it snaps again after the mutation.
+
+  The rest position is now corrected rather than trusted: once the gesture is genuinely over — touch released, the scroller quiet, AND its offset confirmed unchanged across a frame — a scroller that is off a pane boundary is moved to the nearest one. A scroller the browser snapped for itself is left alone, so nothing extra happens on Chrome, and sub-pixel drift on a fractional viewport is ignored.
+
+  That last condition is what keeps the fix from becoming a worse bug than the one it fixes. A quiet period is not proof of rest: iOS runs its own snap animation for a few hundred milliseconds after the finger lifts and fires scroll events irregularly while it does, so a correction that trusts quiet alone can land mid-animation, round an offset still travelling toward next month back to the month it came from, and reverse the swipe.
+- A disabled element answers the pointer with `default`, never an interactive cursor. Every `cursor` in core and lab carries `':is(:disabled,[aria-disabled="true"])': 'default'`, and the reset gives the same cursor to any disabled element that declares none — `[aria-disabled]` included, which previously got nothing. A lint rule and a Chromium sweep over every story keep it that way. Disabled elements sealed behind `pointer-events: none` are unchanged: the pointer never reaches them, so their cursor comes from an ancestor — which is why the guarantee is `default` rather than a distinct disabled cursor the library could only paint on some of them (#5323).
+- Disabled elements no longer paint a hover state: every self-`:hover` in core and lab, and every `:hover` a theme authors, now carries the zero-specificity guard `:hover:where(:not(:disabled,[aria-disabled="true"]))`, so existing overrides weigh exactly what they weighed before. A lint rule and a Chromium sweep over every story keep it that way (#5247).
+- InputClearButton: the clear (✕) affordance now meets the WCAG 2.5.8 AA 24×24 minimum on touch. The shared button rendered a 20px glyph with a 20px tap target, so every input that clears through it — Typeahead, Tokenizer, FileInput and the rest of the family — was under the floor on a phone. An `::after` overlay now expands the tappable region to 24×24, gated behind `@media (pointer: coarse)`: on a fine pointer the overlay is not generated at all, because a mouse is precise enough, an unconditional overlay could overlap neighboring controls in dense desktop layouts, and an overlay covering the button would take hover away from the `astryx-input-clear-icon` theme target. The visual glyph is unchanged at every breakpoint, and the overlay stops at 24px so it stays clear of the 8px adornment gap and the input's own caret area (#4956).
+- MobileNav: the drawer now slides in when it opens, instead of only sliding out when it closes. Two things were needed, and each is useless without the other. First, the dialog is `display: none` while closed, so the drawer's first rendered frame already holds the on-screen transform and a transition has no before-change value to run from — `@starting-style` supplies it, for the drawer's transform and for the `::backdrop`'s opacity. Second, the dialog clipped the off-screen drawer with `overflow: hidden`, which makes it a scroll container; a scroll container in the top layer whose subtree holds another scroller (the drawer's content area) does not paint a `@starting-style` entry transition for its descendants in Chromium — the transition ticks in the CSSOM while every painted frame shows the end value. `overflow: clip` clips identically without creating a scroll container. The drawer now slides in from its own edge (mirrored under RTL) and the scrim fades up, both on `--duration-medium` and both collapsing under `prefers-reduced-motion`, exactly as the close already did (#5218).
+- NumberInput: the number-stepper column now tracks a themed padding and radius instead of assuming the defaults. Theming `number-input` padding left the steppers short of the field edges (a gap top and bottom), and a themed `borderRadius` rounded the field while the stepper corners kept the default radius. The wrapper's padding now goes through the shared container expansion, so it is picked up from any spelling a theme writes it in — `padding: 14px 20px`, `paddingBlock`, or a single `paddingBlockStart` — and both the wrapper and the column read the resulting per-side `--astryx-number-input-padding-*` tokens; an asymmetric `paddingBlock: 4px 12px` is cancelled correctly at each edge. A themed `number-input` borderRadius now also reaches `--_field-radius`, which the column's outer corners follow. Byte-identical by default, and inert for the no-stepper case and every other input (#5181).
+- Stop the container padding system at every overlay boundary. Follow-up to #5209, which zeroed `--container-padding-*` on four overlay roots and closed the visible overflow in #5208 (#5231).
+  Two gaps remained. The variables descendants ADD (`--layout-padding-*`, and a Section's propagated padding) still crossed the boundary, so an unpadded `Section` inside an overlay took the page's padding instead of the theme default — 40px where 16px was meant. And `Lightbox`, `ContextMenu` and `HoverCard` were never covered.
+
+  The reset now lives in one place (`overlayPaddingReset`, exported from `@astryxdesign/core/Layout`) instead of being hand-copied per overlay, and moved onto the `useLayer` root, which covers every layer surface at once. Values descendants subtract are zeroed; values they add are cleared to `initial` so readers fall through to their own default rather than losing their padding.
+
+  Section's padding propagation moved from the public `--astryx-section-padding` token to a private `--_section-padding-propagated`. The two carried different authority under one name — a theme's value versus one ancestor's — and an overlay could not drop the inherited one without blanking the theme's. Propagated values still win over the theme for nested sections, so behavior is unchanged. Themes are unaffected: `--astryx-section-padding` remains the public token and still reaches inside overlays.
+- Theming: a physical `paddingTop`/`paddingBottom` now reaches the container padding expansion, so `card`, `dialog`, `section` and `number-input` track it the way they already track the logical spellings. A physical block longhand matched none of the padding property names the expansion recognizes, so it landed raw on the element while the component's internals kept reading the default — the NumberInput stepper column came up ~10px short of the field edges, and container bleed compensated by the wrong amount. Mixing spellings was worse than either alone: `padding: '10px'` plus `paddingTop: '14px'` published 10px in the tokens while the element painted 14px on top. `padding-top` and `padding-bottom` ARE the block edges in every horizontal writing mode, so this normalization assumes no direction. `paddingLeft`/`paddingRight` are deliberately unchanged: they are direction-relative — left is inline-start in LTR and inline-end in RTL — and the tokens are consumed by logical properties, so routing them would silently move the padding to the opposite edge under RTL. They keep their physical meaning, exactly as before (#5244).
+- `DateInput`, `DateTimeInput`, `DateRangeInput`, and `Calendar` now format and parse dates using the ambient `InternationalizationProvider` locale instead of the host/browser locale. `plainDateFormat` (backing `formatSharedDate`) previously called `Intl.DateTimeFormat(undefined, ...)`, and `dateParser`'s day/month disambiguation heuristic for ambiguous numeric input (e.g. `3/4/2026`) called `Intl.DateTimeFormat()` with no locale at all, so a tree wrapped in a non-English `locale` still formatted and parsed dates using the host locale (#5120).
+- Use the InternationalizationProvider locale for sorting, formatting, and speech defaults (#5195)
+- RadioListItem: the whole row is now a click target. Clicking the description — or the empty space in a row's hover area — selects the radio, matching CheckboxListItem. Previously only the radio and its label text responded, so the description and surrounding row were dead space. The row delegates surface clicks to the radio input (one tab stop per option preserved), and the radio keeps its accessible name via `aria-label` (#5143).
+- Reset container padding custom properties on overlay elements (`BottomSheet`, `Dialog`, `MobileNav`, `Popover`) to prevent nested `Section` components from inheriting ancestor section padding (#5209).
+- ResizeHandle: dragging the lower half of a tall handle works again. The invisible grab zone is stretched along the handle, but the offset that biases it onto the pill also carried the pill's own `-50%` centering shift — so the zone slid half the handle's length off the divider. On a full-height panel at 1440x900 the 16x900 hit box sat at y=-434, leaving everything below the pill's centre dead: a pointerdown on the visible grip's centre, or anywhere lower, started no drag at all. The dead region grew with the panel, and the same shift stranded the grab zone sideways on vertical handles. The bias now moves the zone along the pill's axis only (#5198).
+- Opening a Dialog, BottomSheet, Lightbox, or MobileNav no longer shifts the page sideways when the browser has a classic scrollbar (#5219)
+  Locking background scroll hides the document's scrollbar. Where that scrollbar takes layout space — Windows/Linux desktop, and macOS set to always show scroll bars — hiding it widened the layout viewport by its width (~15px), so the whole page reflowed sideways behind the overlay and back again on close.
+
+  Both scroll locks now hold that gutter open with `scrollbar-gutter: stable` for the duration of the lock, which keeps `position: fixed` chrome (sticky headers, toast viewports) still as well as in-flow content. Pages with no space-taking scrollbar, and pages that already set `scrollbar-gutter` themselves, are left alone. Engines without `scrollbar-gutter` support fall back to padding the measured difference.
+- SegmentedControl: keep item labels on a single line, truncating overflow with an ellipsis instead of wrapping to multiple lines (#5035)
+- Selector: `SelectorOptionData` gains `description`, and the closed trigger now shows the selected option instead of just its label. The two-line option row `SelectorOption` draws was unreachable from the `options` prop — the data type carried only `value/label/disabled/icon` — so consumers kept a side map of descriptions keyed by value and re-rendered the row through `renderOption`. `description` now sits on the option data and `DefaultOption` forwards it. On the trigger, the selected option's own `icon` renders in the closed state (`startIcon` still wins when set, so a pinned field icon never doubles up), which retires the app-side `startIcon={value === 'x' ? … : …}` mirroring of state the component already knows. `renderValue` is the seam for drawing the selection yourself — the description included (#5202).
+  [feat] Item: new `layout` prop — `'stacked'` (default, unchanged) or `'inline'`, which keeps the description on the label's line with the description ellipsizing first. The inline row centers its two lines rather than sharing a baseline: two font sizes on one baseline make a line box taller than either line, which would push a fixed-height host off its size token. Every row built on `Item` gets the axis, `SelectorOption` included.
+
+  [fix] Selector: the trigger is sized by padding rather than a fixed height, so it is the `--size-element-*` token for a one-line value (28/32/36) and exactly one text line taller for a two-line one (48/52/56). The token and a text line are both multiples of 4, so every trigger lands on the 4px rhythm and lines up with the Buttons and inputs beside it — and no prop chooses the height, the content does. It previously swapped the fixed height for a minimum whenever `renderValue` was passed, keyed on the prop being present rather than on the content needing the room: a one-line value measured 39px and a two-line one 58px at _every_ size, so the `size` prop stopped affecting the trigger at all. Inside an `InputGroup`, where the group pins the row, the relaxed height did nothing and the content bled 4px through its own border. The group owns the row now and the trigger clamps its own value box to it, so nothing a caller draws can paint over the rows above and below: a `SelectorOption` folds onto one line and ellipsizes, and any other node is cut off at the row's edge. The trigger also stops asserting a height floor of its own there, so a control sized above its group — `<InputGroup size="md">` around a `size="lg"` control — sits in the group's row instead of growing it. The trigger's line box is pinned to that same token rather than a ratio, so the coarse-pointer font bump — and any theme that changes `--font-size-base` — grows the glyphs without moving the control off its size token.
+- `Slider` with `orientation="vertical"` now gets the same 24px touch hit area the horizontal one got: its track was still only 20px wide on coarse pointers, under the WCAG 2.5.8 AA minimum. The whole track is the tap target for both orientations — the fix that floored the horizontal track's block size did nothing for vertical, whose short axis is the inline one — so the inline size is now floored to 24px on touch, with the same `@media (pointer: coarse)` gate. The rail, fill, marks and thumb all center on the inline 50%, so nothing visible moves and desktop is untouched (#5173).
+- `@astryxdesign/core/theme/syntax` is importable from a server component again: the presets are data, not client references (#5076).
+  The subpath's barrel carried `'use client'`, and it is the only entry point for the syntax module. React therefore replaced _every_ export with a client reference for a server importer — including `dracula`, `oneLight`, `allSyntaxPresets`, `syntaxTokenDefaults` and `defineSyntaxTheme`, none of which need a boundary. Reading a preset in a Next.js server module (deriving a code-block ground, emitting theme CSS at build time) got a proxy instead of data, so `preset.tokens` was `undefined` and the failure surfaced far from its cause — the same import under plain Node worked perfectly.
+
+  The directive now sits only on `SyntaxTheme.tsx`, the provider that actually needs it, so `SyntaxTheme` and `useSyntaxTheme` keep their client boundary while the data exports resolve as data. No API change.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @ernestt
+- @freddymeta
+- @Geervan
+- @HelloOjasMutreja
+- @imdreamrunner
+- @nynexman4464
+- @rubyycheung
+
+---
+
 # 0.4.5
 
 #### New Features
@@ -10,6 +143,7 @@
   Nothing changes unless you ask for it: `InternationalizationProvider` still defaults to English, and the catalogs are loaded through the existing `./locales/*.json` export. An app that already passes a `locale` now gets translated component strings where it previously fell back to English.
 
   The catalogs come from Crowdin and are refreshed nightly (#5186), so a translation landing upstream reaches a release without anyone opening a PR by hand.
+
 - DateRangeInput / Calendar: add `maxRangeSpan` and `minRangeSpan` to constrain the size of a selected range. Once a start date is picked, days outside the allowed window are disabled — e.g. `maxRangeSpan={7}` keeps the range within a 7-day window of the start (#5145).
 - FormLayout: add `defaultOptionality` — set a form-wide default (`'optional'` or `'required'`) so only the exception carries a visible indicator. Under `'optional'` only `isRequired` fields show one; under `'required'` only `isOptional` fields do; a field that restates the default shows nothing. Under `'required'` the unmarked fields also expose `aria-required` so screen readers match what sighted users see — resolved on `aria-required` only, never the native `required` attribute. Unset keeps today's per-field behavior (#4791).
 - Add `astryx-input-clear-button` theme target on the shared clear button wrapper. Themes can now control the clear button's height and hover independently of other ghost buttons — for example suppressing the hover fill or matching a different element size scale (#5093).

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