What's New

Release notes and changelog for all packages.

0.5.1

New Features
  • add shape prop ('circle' | 'rounded' | 'square') to Avatar for non-circular form factors (#4205) (#4327)
  • Card: make the variant axis theme-extensible through a CardVariantMap interface (#5551) CardVariant was a hand-written union backed by a closed style record, so a theme could not add a card variant: an unknown value neither type-checked nor rendered. It is now keyof CardVariantMap, an interface exported from @astryxdesign/core/Card that a theme build augments — the same shape Button, Badge, Section and the other extensible axes already ship.
    keyof CardVariantMap resolves to exactly the thirteen values CardVariant had, so no existing call site changes. A variant a theme adds falls through to base styles and the theme's own card['variant:<name>'] rule paints it.
    On SelectableCard that variant's selection ring is drawn in --selectable-card-ring-color, defaulting to the accent. No token the component could pick is guaranteed to contrast with a fill the component cannot know, so a theme rule that adds a variant sets the ring colour in the same rule as its backgroundColor.
  • CheckboxInput and Switch now name their own label as a theme target: astryx-checkbox-label and astryx-switch-label, alongside the astryx-field-label every label already carries. A theme could previously only reach one astryx-field-label target, so styling a checkbox's label — which shares a row with its control — meant styling every form field's label above its input too. The control passes the target down, so the name says what the thing is rather than encoding how it is arranged, and nothing can set it untruthfully. (#5183)
  • The checkbox indicator now exposes stable theme targets for its two marks — astryx-checkbox-indicator-check (the checkmark) and astryx-checkbox-indicator-dash (the indeterminate bar) — mirroring the existing astryx-radio-indicator-dot. Both reflect size. A theme restyling the mark itself (stroke weight, colour, the dash's proportions) previously had to reach it with .astryx-checkbox-indicator > svg and > span, which are element-and-order selectors that break silently on any restructure. Purely additive; no visual change. (#5426)
  • ComplexSelector: onOpenChange reports every open and close of the popup — the trigger, the keyboard, a light dismiss, Escape, content calling close(), or the imperative handle. Paired with the existing handleRef, a consumer can drive and observe the surface without reading the shell's DOM. (#5211)
  • DateInput uses the platform date picker on touch, with nativePicker to choose the native or Astryx surface; focused desktop-style native fields reveal their editable segments, the Astryx touch sheet keeps Reset in its header and Save alone in its footer, and both closed surfaces match standard input height (#5261, #5456, #5502, #5534) nativePicker="touch" is the default, "always" uses <input type="date"> wherever supported, and "never" keeps Astryx's sheet or popover. Formatting still returns on blur, and min/max continue to validate native selections.
  • Add a coarse-pointer DateTimeInput bottom-sheet picker with separate closed Date/Time segments, direct section opening, and a two-step Save date → Save flow. (#5582)
  • Icon APIs and themes accept namespaced extension keys, and NumberInput steppers use numberInput:stepperDown without widening the required IconRegistry keys (#5466) <Icon icon>, useIcon, and defineTheme({icons}) accept keys such as numberInput:stepperDown and richtext:bold; misspelled built-in names remain type errors. NumberInput keeps a compact centered Core fallback, while themes can override its steppers independently from the shared chevronDown semantic.
  • OverflowList can now hand its collapsed items to a menu you already render, via onOverflowChange(overflowItems). overflowRenderer only describes an indicator the list mounts itself, and only while items overflow — so a row that already carries a standing "…" menu had no way to collect the collapsed items into it, and adding an indicator gave the user two menus side by side. Watching from the outside was not reachable either: a reporter component placed inside overflowRenderer mounts twice (the hidden measurement copy always receives every item, so it cannot tell you what is actually collapsed), and nothing fires when the row widens back out and the set empties. The new callback reports the collapsed set whenever its membership or order changes, and leaves the anchor entirely to the caller. It fires once measurement has collapsed something, fires again with an empty array once the row widens back out and everything fits, and is silent while nothing overflows — including on mount, so a list that fits from the start never calls it. It never reports the pre-measurement state, which is an empty set whether or not the row actually overflows; hold the collapsed set in state initialised to [] and it is correct at every moment. Reports run from a layout effect after measurement, so the menu updates in the same frame as the collapse. The measurement container is now observed for size changes, so child-size changes refresh every OverflowList and direct useOverflow consumer even when the available container width does not change. Keyed membership and order changes are re-measured before onOverflowChange reports them. Stable React keys distinguish same-count membership and order changes, while unrelated re-renders and callback identity changes do not re-fire it. Both APIs may be used together; using onOverflowChange alone adds nothing to the row. (#5199)
  • Selector and MultiSelector: configurable panel empty states via emptyText and emptySearchText, announced to screen readers as well as shown; a panel with no options now says so instead of rendering blank, and says nothing while isLoading (#5462)
  • SideNavItem: new actions slot for row-level secondary controls (icon buttons, menus). Content renders as a sibling of the primary link/button — after the expand/collapse toggle, before nested children in DOM and focus order — so interactive controls never nest inside the primary element and every row control is reachable before focus enters the subtree. Passive content (badges, counts) stays in endContent; actions is hidden while the rail is collapsed, and stays interactive on disabled items since each supplied control owns its own disabled state. An actions row draws its focus ring as a full-row pill for the primary link or button, while the expand/collapse toggle and each supplied action keep their own — adds focusOutlineProps.focusWithinFirstChild and focusOutlineProps.suppressed for that pairing. Supplied controls inherit the row's control size through SizeContext, the way SideNav already cascades one size to its footer icons, so an unsized icon button comes out the same box as the built-in toggle; an explicit size still wins. (#4988) (#5005)
  • Spinner: the ring's geometry and its two colors are now themeable. The size and shade props keep their fixed enums; what each named value resolves to is now a theme's to set, through four public custom properties on the spinner target — --spinner-diameter and --spinner-stroke-width under a size variant, --spinner-color and --spinner-track-color under a shade variant (or on the base target for all of them at once): (#5214)
    ts
    spinner: {
    'size:xl': {'--spinner-diameter': '2.5rem', '--spinner-stroke-width': '0.375rem'},
    'shade:subtle': {'--spinner-track-color': 'transparent'},
    }
    Any length and any color notation works — rem, em and calc() are resolved by the cascade into the radius and stroke the ring is drawn with, and colors accept var(), color-mix() and currentColor. A stroke width of 0 is honoured as a zero-width stroke — it paints nothing, rather than being read as "unset" and silently drawing the default. The drawn ring and the box around it come from the same values, so they stay in step, including when a media query or a root font-size change moves them after mount.
    The two private vars the ring resolves into are registered as <length> when the module is imported, not when a spinner first mounts. Registering an inherited property with an initial-value invalidates style for the whole document, and a spinner is the loading indicator — it arrives on a page that has already rendered, so paying that there is paying it on the full tree: 29 ms against 12 ms for the same mount on an 11k-element page. A build that never imports Spinner drops the module and the registration with it.
    Output is unchanged for every size and shade unless a theme overrides something, and so is every precedence around the box: it is still sized by an inline width/height written after the caller's style, as it has always been, with the composed value in place of the number.
  • TextArea: the two painted elements inside the wrapper now carry stable theme targets — astryx-text-area-control (the <textarea> itself) and astryx-text-area-counter (the character counter). Only the wrapper was themeable before, so a theme restyling the control's own typography, placeholder or resize affordance, or the counter's supporting text, had to reach in with structural selectors like .astryx-text-area > textarea. Purely additive: no existing class, data attribute, or style changes. (#5418) Neither carries a size axis. size moves only the control's block padding (sm and md are empty; lg sets paddingBlock), and that is the axis a padding translation for this component takes over — so an axis here would be a second way to say the same thing, and the one that stops being true once the translation lands.
    The start-icon and end-slot overlays are deliberately not targets. They paint nothing — each is position: absolute; pointer-events: none; display: flex — and they are placed off the wrapper's --_textarea-inline-padding, so a theme that moves the control's inset needs them to move with it rather than to be re-placed one at a time. That inset belongs in a padding translation for the component, which is tracked separately.
  • Toast: renderContent on the showToast options replaces the content of that toast's card with your own layout. (#5428)
    tsx
    showToast({
    body: 'Your changes have been saved.',
    renderContent: ({body, endContent, dismiss}) => (
    <MyRow>
    <MyTitle>{body}</MyTitle>
    {endContent}
    <Button label="Dismiss notification" onClick={dismiss} />
    </MyRow>
    ),
    });
    Astryx keeps the card, its astryx-toast theme target, live-region role and auto-hide behavior. The renderer receives the message, endContent, resolved toast settings and a dismiss callback.
    Custom content owns its complete layout and every control in it. Call dismiss from the control that should close the toast; it may be passed through nested components. Astryx does not register an injected component or add a fallback close behind a custom layout.
    The API is per-toast. An app can share one layout by wrapping useToast() and passing renderContent on each call, while other toasts continue to use the ordinary Astryx layout and its translated, themeable dismiss Button.
    New exported types: ToastContentRenderProps, ToastContentRenderFn.
  • Toast now supports touch and pen swipe dismissal toward its configured viewport edge. The vertical axis matches each Toast's top/bottom placement and entrance/exit motion, so the dismissal follows the same spatial model instead of introducing a separate side exit. Native touch scrolling is preserved until movement resolves to the dismiss direction, interactive controls do not start a swipe, and swipe continues to report the existing manual dismissal reason. Pen is included as direct-contact input; mouse drag is excluded because desktop users already have the visible close control and dragging can conflict with text selection. (#5375)
  • Typeahead + Tokenizer: minQueryLength holds the search and the menu until the query is long enough (#5385) Also fixes a stranded loading state that predates the prop: abandoning an in-flight search — by emptying the field, by falling below the threshold, or by selecting an item while the next search is still out — bumps the search generation, which makes that search's own finally decline to clear the loading flag. The field kept reporting "Loading" to assistive technology until another search settled.
    hasCreate is not gated by it. The "Create ..." entry is derived from the typed text rather than fetched for it, so it now reaches the menu through a separate internal path and is offered whatever the threshold says — the threshold exists to avoid a fetch too broad to be worth making, and creating costs no fetch. With minQueryLength={3}, typing QA offers Create "QA" and Enter commits it, while the search source is still never called.
    One consequence worth naming: the Create entry is appended after the results are cut to maxMenuItems, so with hasCreate a full menu now shows one option more than the cap — 11 where it used to show 10. The cap bounds how many results a menu shows; creating is a separate capability and is not crowded out by them.
Fixes
  • AlertDialog lets Dialog preserve and clamp its preferred width, lets whole actions move to another row when needed, and stacks full-width destructive and Cancel actions at 640px and below while preserving standard single-line Button sizing and labels regardless of pointer type. (#5343)
  • Badge: a long label no longer escapes its container. (#5558) Badge set white-space: nowrap with nothing to clip it — the one pairing that neither wraps nor truncates. A label wider than the space available rendered outside the badge's container and over whatever sat beside it.
    tsx
    <div style={{width: 100}}>
    <Badge variant="pink" label="Awaiting security review" />
    </div>
    Measured in Chromium: that badge came out 163px wide in a 100px column, spilling 63px past it; in a fixed-layout table cell it painted 64px over the text in the next cell. The badge now clamps to the width it is given and cuts the label with an ellipsis.
    A badge that already fits is untouched — same width, same height, same DOM. Measured before and after, a badge with room to spare is 53px either way; only the cases that were already overflowing change. Badge uses no hooks and stays server-renderable.
    The ellipsis sits on an inner label span rather than the badge itself, because text-overflow needs a block container and taking the root off inline-flex to get one would cost the icon its centring. With an icon, the icon holds its place and the label gives way.
    So that a clipped tail is not simply lost, a string or number label is also carried in the badge's title — the same shape BaseTable already uses for a truncated header cell. That costs no measurement and no hook, so Badge still renders the same on the server and stays usable in a server component. A rich label is left alone rather than flattened to a guess.
    Two gaps remain, both needing runtime measurement, and both tracked in #5585: the title is set whether or not the label actually fits, and a native title is a pointer affordance — it answers hover, not keyboard focus, and not touch at all. The refinement is a tooltip shown only when the text is really cut, reachable by hover and by focus, which makes Badge a client component and is its own trade-off to weigh.
  • Banner names each dismiss control after its string title, so stacked banners no longer expose identical "Dismiss" buttons to screen readers. Rich titles retain the generic translated name unless the consumer supplies an already-translated dismissLabel; that override also labels the tooltip. (#5113)
  • Seven components now forward the pass-through props promised by BaseProps (#5563) MetadataListItem, NavHeadingMenu, Timestamp, Token, TopNavMegaMenu, TopNavMenu, and TypeaheadItem now forward neutral aria-*, id, tabIndex, event-handler, and data-* props to their rendered DOM element. Styling still merges through mergeProps, contract-owned attributes retain precedence, and owned handlers compose through composeEventHandlers with the caller first.
    MetadataListItem targets its wrapper <div> when stacked and its <dt> when inline. A TypeaheadItem backed by caller-supplied item.element remains unchanged and does not receive forwarded props because that value may not be a cloneable element.
    This completes #5254 after #5288 by @lexs landed List and Markdown first, followed by #5493 by @gonzoblasco for TreeList.
  • Button now reflects elevation as a theme target. The prop selected between four StyleX style objects but was missing from the sibling themeProps('button') call, so data-elevation never reached the DOM and no theme could style the axis — the same defect fixed on Card in #5491, and one ButtonGroup already had right. A button inside a ButtonGroup reports none, because the group owns the surface's elevation and the member paints flat. Every wrapper that forwards ButtonProps through to Button — IconButton — picks the reflection up with it. (ToggleButton does not: its props extend BaseProps, not ButtonProps, so it has no elevation to forward and keeps reporting none.) Nothing about the rendered button changes: 60 of 64 captured frames are byte-identical, and the four that differ do so only inside the loading spinner's own box. (#5552)
  • Calendar: announce a cleared range in the provider locale, wrap the two-month layout instead of overflowing a narrow viewport, keep the selected date visible under forced colors (#5453)
  • Card: reflect elevation as a theme target so a theme can reach it, and correct the documented padding default (#5491) elevation picked a style object but never reached the DOM, so astryx-card exposed data-variant and nothing for elevation and a theme could not style the four shadow tiers. It now rides themeProps alongside variant.
    The padding prop documented 4 as its default. With the prop omitted the card reads the theme's card padding, and most shipped themes set that to a different step, so writing the documented default explicitly changed the card's size. The prop docs, the JSDoc and the playground default now say that omitting the prop takes the theme's padding and passing a step overrides it. The four effectivePadding !== 4 style branches that encoded the same wrong default in code are gone: container() already sets every variable they set, verified identical across all eleven padding steps on both a bordered and a borderless card.
  • Carousel no longer drops keyboard focus to the document body when reaching a scroll edge disables the nav button in use. Focus moves to the opposite arrow instead, on the state transition that disables the button rather than on a prediction from the press, so it holds under reduced motion, under scroll-snap, and on browsers without scrollend. The scroll container is also now a documented theme target, astryx-carousel-scroller, carrying the gap, padding, snap and edge-fade props it styles, so a theme can reach the spacing and the fade it could not see before. (#5601)
  • The 56 --color-data-* defaults now reach runtime CSS and built themes from the same source, while dashboard template fallbacks match those defaults (#5562, #5566) The defaults live once at :root in @layer astryx-base, so nested themes inherit parent overrides and astryx theme build matches <Theme> while generateThemeCSS keeps its existing return shape.
    Visual change. A chart or template that previously painted nothing or used a mismatched hex fallback now paints the data token's default. Pin an explicit color to preserve a previous fallback.
  • DateRangeInput: allow a same-day range when minRangeSpan is 1 (#5581) A repeated click on the range start now commits a one-day range when the configured minimum permits it, including when a maximum span is also set. Longer minimum spans keep the existing cancel behaviour so the user can move the start date.
  • Dialog: fullscreen safe-area padding follows writing direction and defers to explicit padding (#5367) Two corrections to the fullscreen safe-area padding that shipped in 0.5.0.
    The insets were mapped to the wrong edges in RTL. env(safe-area-inset-left) and env(safe-area-inset-right) are physical, but they were assigned straight to padding-inline-start and padding-inline-end, which are logical. That holds in LTR and inverts in RTL, where inline-start is the right edge — so a device notch on the physical left padded the edge away from it and left the notched edge unprotected. Each physical inset now feeds the logical edge that actually faces it, in both directions.
    Safe-area protection overrode explicit padding. The max() was applied to the fullscreen surface unconditionally, so it beat both a padding prop and a theme's dialog: {padding: 0}, and a deliberately full-bleed fullscreen dialog could not be expressed. It now sits in the innermost fallback of the same --astryx-dialog-padding* chain container already resolves, so it applies only when no padding is set anywhere. An explicit value, 0 included, is honored as written.
  • Date formatting now defaults to Gregorian calendar semantics across core, charts, and Schedule while still following the selected locale for language, numbering, and field order. (#5303) The low-level public plainDateFormat helper continues to honor an explicitly supplied calendar option for compatibility; Astryx components do not expose that display-only exception and remain Gregorian. The deterministic English fallback also prevents server and browser locale differences from producing hydration mismatches when no provider locale is available. Locale-aware parsing only selects day-first or month-first order for ambiguous ASCII numeric dates; it does not parse localized month names, non-ASCII digits, or arbitrary locale-specific strings.
    Fixes #5074.
  • Labelled HoverCard triggers expose a dialog-popup relationship without flattening rich content into a description, and only roles that support aria-expanded receive that state (#5419, #5501) The trigger now uses aria-haspopup="dialog", aria-controls, and a role-gated aria-expanded; useHoverCard exposes the layer id and open state, while describedBy remains as a deprecated alias for compatibility. Unlabelled group cards keep their description relationship.
  • Popup triggers no longer fight the browser's own light dismiss: pressing the button of an open Selector, MultiSelector, ComplexSelector, DropdownMenu, or Popover closes it once instead of closing and reopening. MultiSelector's clear and status buttons also keep its popup open when pressed. (#5018)
  • Markdown now applies the same URL safety rule to every image path it parses: reference-style images (![alt][label] and the shortcut form) and standalone block images pass through the check inline images and links already used, and the render-side guard normalizes control characters before testing so both layers see a URL the way a browser will. (#5522)
  • Markdown and List forward the rest of BaseProps (#5288) Both declare BaseProps, and BaseProps documents that data-*, aria-* and role reach the element — but each destructured a fixed set of props and forwarded only data-testid, so an aria-label a consumer passed silently disappeared. <Markdown aria-label="Release notes"> named nothing, and a list could not be labelled by a heading it did not render itself.
    Consumer props spread first, so what a component sets for itself still wins: the block root stays role="document", the list keeps the explicit role="list" that restores Safari/VoiceOver announcements, and a list rendering its own header keeps that association rather than one pointed elsewhere. The aria-labelledby for that header is only written when the header exists — writing undefined unconditionally would erase a consumer's own label.
  • NumberInput parses locale-formatted paste safely and commits one complete draft: grouped numbers and machine decimal points work, arbitrary repeated punctuation is refused, out-of-range values clamp to the nearest bound, and fractional stepping cannot cross a rounded bound (#5152, #5450, #5459, #5510, #5546) Invalid typed or pasted input preserves the prior value instead of committing a valid prefix. Pagination inherits the complete-draft and bound behavior, while inline Table filtering and PowerSearch keep their existing live and Enter-to-save behavior.
  • Popover: theming popover.borderRadius now changes the rendered radius. The astryx-popover target moves onto the popup surface — the box that paints background, radius and elevation — and usePopover reads the registered --_popover-radius there instead of hardcoding --radius-container. Content padding moves with it, so a themed padding still replaces the default instead of nesting inside it. (#5162)
  • Ensure pressed overlays override hover across interactive surfaces (#5451) (#5516)
  • Stack DateTimeInput's date and time fields when its container is narrower than 400px. (#5609)
  • Selector: a caller-supplied id now drives the trigger's whole identity, not just its id attribute (#5561) Selector generated its trigger id with useId() and set it on the trigger button before spreading ...rest, so a caller's id — accepted through BaseProps — replaced it on the button while the generated value stayed behind as the target of the listbox's aria-labelledby and of the Field label's htmlFor. Passing id therefore left the listbox with no accessible name and the field label pointing at an element that does not exist, silently and with a clean typecheck, lint and build.
    The internal identity is now derived from the caller's id when there is one, so the button, the listbox's aria-labelledby (both the plain and the hasSearch panel) and Field's inputID all name the same element. The trigger's own id attribute is unchanged in every case; what changes is that references which used to dangle now resolve — including the field label, which consequently regains its native click-to-focus behaviour. With no id supplied the rendered output is identical to before.
  • Selector raw source now compiles when consumer Babel presets lower arrow functions before StyleX extraction (#5508)
  • Platform detection reads the client-hints Unknown sentinel as no answer, and lives in one place (#5394) Follow-up to #5325, which taught useHotkeys and Kbd to fall through to navigator.platform when userAgentData.platform is blank. Unknown is the User-Agent Client Hints spec's own value for "cannot say", and it names a platform no more than '' does, yet it still committed to the client-hints branch and answered "not Apple". It now falls through the same way.
    The two detections were independent copies kept aligned by a docstring. They are now one internal util that both import, so the next change to this logic cannot land on one surface and miss the other. The util is deliberately not named in utils/index.ts, which would publish it as API.
  • SideNavItem: the standalone expand/collapse toggle on a collapsible item with an href or onClick now carries the box of a size="sm" icon button. It had no box of its own, so it shrank to the 24px chevron inside it and painted a smaller hover pill than any icon button sitting beside it in the same row. (#4988) (#5005)
  • SideNav: collapsible and resizable no longer keep two independently initialized copies of the collapse state. Both props are normalized into one internal collapse config with a single owner — the resize hook when resizable is in play, SideNav's own state otherwise — so the hook can no longer restore itself collapsed while SideNav renders the expanded layout at width 0, which is what made a persisted-collapsed nav come back invisible and unrecoverable (#4790) — that the second independently-initialized boolean is the defect, rather than the restore clamp, is @HelloOjasMutreja's diagnosis from #4853. Passing both props stays supported and every configuration that works today resolves to the same collapse state it does now; when the two props genuinely address the same state (defaultIsCollapsed on both, or a controlled collapsible alongside collapse state on resizable) resizable wins and a dev warning names the conflicting keys. useResizable gains the standard controlled/uncontrolled pair, defaultIsCollapsed and isCollapsed, alongside the existing onCollapseChange: uncontrolled it owns collapse as before, controlled the prop wins and collapse(), expand() and a drag past the threshold report through the callback instead of mutating. Persisted entries now store {size, isCollapsed} where size is the expanded size — the encoding is @AKnassa's from #4824 — so a reload restores the collapsed rail and expanding returns to the width the user had rather than defaultWidth; legacy entries still load, with a plain number read as a width whose collapse state is unknown and a plain 0 (written by the old collapse path) read as collapsed, so anyone already stuck with an invisible nav recovers without clearing localStorage. resizable can now also carry collapse state on its own. Two notification changes ride along: with a single owner, collapsible.onCollapsedChange fires once per toggle on a resizable nav instead of twice; and the hook's collapse callbacks now read the live collapse state rather than the value captured at their last render, so one drag past the threshold reports one collapse instead of one per pointer move, dragging back above the threshold re-expands mid-gesture, and resize() out of the collapsed state reports the implicit expand. That last fix is @AKnassa's, from #5118. (#5075)
  • Slider: dragging the thumb with a mouse no longer draws the keyboard focus ring (#5463) The thumb is a div[role="slider"], and the track's pointerdown handler calls preventDefault() and then focuses the thumb from script. Chromium treats that script focus as focus-visible, so :focus-visible matched on mouse-down and every drag came with a 2px accent ring — measured in Chromium, not inferred.
    :focus-visible stays the CSS condition; it is now narrowed by the existing interactionModality utility, the same way PanelSearchInput and Selector narrow theirs. Keyboard focus rings exactly as before, and a mouse grab of a thumb that already had the ring drops it.
    One deliberate difference from the text-input cases: a keypress after a mouse drag brings the ring back. A text field has a caret to show where input is going, and a slider thumb has nothing else.
  • Keep useResizable callbacks stable when snap points are omitted. (#5276)
  • Keep useLayer trigger refs and return objects stable when their inputs are unchanged. (#5272)
  • Keep useTheme token resolvers and return values stable when the resolved theme is unchanged. (#5274)
  • Table sticky columns: the pinned-column shadow now reads the theme's --color-shadow token instead of a hardcoded light-dark() tint, so a theme can retint it. (#5445) The tint was light-dark(rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0.32)) written in the component, chosen because --color-shadow (10%/30% alpha) read as slightly too faint. A literal in a component is the one place a theme cannot reach: every theme got this exact black regardless of its own shadow colour, and the two-point alpha difference bought nothing for it — rendered, the token version differs by at most 5/255 on any channel in light mode and 1/255 in dark, over the ~0.4% of the frame the two shadow strips occupy.
    Reading the token instead means the seven bundled themes each tint this shadow with the value they already declare for every other shadow (chocolate [#4](https://github.com/meta/astryx/pull/4)a35201A, stone [#25252](https://github.com/meta/astryx/pull/25252)a1a, and so on), and a custom theme gets the same reach.
  • Syntax-highlighted punctuation (brackets, commas, semicolons, operators) now meets WCAG 2.1 AA contrast (4.5:1) against the code surface in every bundled theme. (#5414) --color-syntax-punctuation borrowed --color-text-disabled, a token WCAG deliberately exempts from the normal-text contrast requirement because it marks an inactive control. Punctuation in a code sample is always-active, normal text, and measured well under 4.5:1 in three themes: neutral (2.42:1 light, 2.53:1 dark), chocolate (3.06:1 light, 2.56:1 dark), and matcha (3.83:1 light, 2.73:1 dark). The other four themes (butter, gothic, stone, y2k) already defined their own passing punctuation colour and are untouched.
    The shared default now points at --color-text-secondary instead (used for --color-syntax-comment too, and already verified to clear AA). Neutral, chocolate and matcha each get a dedicated punctuation colour in their own syntax palette, since they define one rather than inheriting the shared default: neutral [#6](https://github.com/meta/astryx/pull/6)e6e6e/#a0a0a0 (4.89:1/7.57:1), chocolate [#9](https://github.com/meta/astryx/pull/9)e622e/#cb884d (4.84:1/6.12:1), matcha [#566](https://github.com/meta/astryx/pull/566)a39/[#92](https://github.com/meta/astryx/pull/92)af6a (5.19:1/7.02:1).
    Adds scripts/check-syntax-punctuation-contrast.test.mjs, resolving each theme's --color-syntax-punctuation/--color-syntax-background pair through light-dark()/var() indirection (the pattern from #4446's badge contrast guard) and holding every theme, both colour schemes, to AA — so a regression here fails the build instead of shipping.
  • Table keeps grouped headings and selected-row washes visible across frozen columns while scrolling sideways (#5454) useTableGroupedRows pins its default heading and collapse control to the table's start edge. useTableSelection now publishes and withdraws the selected-row overlay with the row background, so the wash continues under sticky cells.
  • Text, Heading: a truncated label shows one tooltip, not two. (#5559) When maxLines clipped the text, both components rendered Astryx's Tooltip and set the native title attribute to the same string. Hovering drew both: the styled tooltip first, then the browser's own unstyled one on top of it a moment later, saying exactly the same thing.
    The title goes. Tooltip already wires aria-describedby onto the anchor, and the full text is in the DOM either way — CSS clips it visually, so a screen reader was never reading the truncated version. Nothing is lost but the duplicate.
    Measured on hover, same story, before and after: 2 tooltips shown to the user, then 1.
  • Seven theme target roots that ran a compound component name together are deprecated onto the <component-kebab>-<part> spelling the component's name implies: codeblock → code-block (with -copy-button, -header, -title), progressbar → progress-bar (with -fill, -mark, -track), hovercard → hover-card, statusdot → status-dot, textarea → text-area, navicon → nav-icon, and Table's second root base-table → table (both named the same <table> element). A defineTheme key that matches no target fails silently — no error, no warning, the rule never emits — so someone who read ProgressBar and wrote 'progress-bar' got nothing and no explanation. Nothing breaks: every component renders both classes and both keys resolve, including the derived vars a renamed key expands into. New themes should use the canonical spellings; the deprecated aliases remain supported. (#5449)
  • Toast fits narrow and safe-area viewports, aligns wrapped actions and dismissal, uses edge-directed entrance and exit motion, exposes the Notifications landmark only while populated, and keeps exactly the viewport gutter below the final toast (#5353, #5460) Inter-toast spacing is 8px, while the visual bottom no longer adds a trailing toast gap on top of viewport padding. Placement, visible-stack limits, auto-hide defaults, announcement semantics, and dismissal reasons are unchanged.
  • TreeList: forward aria-label/aria-labelledby to the role="tree" element so a tree can be named (#5493) TreeList destructured a fixed set of props with no rest spread, so every BaseProps attribute (aria-*, role, tabIndex, id, event handlers) was dropped and never reached the DOM. A tree without a visible header could not be named at all - a screen reader announced an unnamed tree with no way to know what it was.
    The component now spreads the remaining props onto the root element and routes aria-label/aria-labelledby onto the <ul role="tree"> itself, so <TreeList aria-label="File tree"> names the tree. When a visible header is rendered, it keeps naming the tree (AT hears the same name the user sees); a consumer-supplied aria-labelledby only applies on the headerless path. The contract role="tree" is written after the rest spread so a consumer cannot displace it.
Documentation
  • useAnnounce, useTypeahead, useInteractiveRole, useLongPress, useInputStatusIcon, useDevWarning and useIndicatorFocusRing are now discoverable. The CLI's hook index is built from the .doc.mjs files next to each hook, and these seven shipped without one; so astryx hook <name> answered "No hook named", astryx hook omitted them and astryx search never returned them, while the package exported them with full TSDoc. Agents following the documented discovery workflow concluded the primitives did not exist and hand-rolled replacements; for useAnnounce that means a hand-built aria-live region, which usually does not announce at all. A test now fails when a hook is exported from the barrel without a doc, so the index cannot silently go stale again. (#5109)
Contributors
Thanks to everyone who contributed to this release:

0.5.0

Breaking Changes
  • Banner: the collapse axis moves onto one collapsible prop, and content can opt out of collapsing (#5255) Banner inferred its disclosure from its content: any children got a chevron in the header and were hidden until it was pressed. There was no way to show content without a toggle — the case a banner most often wants, a list of the three fields that failed validation — and defaultIsExpanded was the only knob, with no controlled mode.
    The whole axis is now one boolean | CollapsibleConfig prop, following the boolean-or-config convention SideNav.collapsible set, and backed by the shared useCollapsible hook rather than Banner's own state:
    tsx
    <Banner status="error" title="3 fields need attention">…</Banner> // unchanged: collapsible, starts closed
    <Banner collapsible={false}>…</Banner> // new: always visible, no toggle
    <Banner collapsible={{defaultIsOpen: true}}>…</Banner> // replaces defaultIsExpanded
    <Banner collapsible={{isOpen, onOpenChange}}>…</Banner> // new: controlled
    The default is unchanged — a banner that never mentioned defaultIsExpanded behaves exactly as it did. The breaking part is the prop itself: defaultIsExpanded is removed in favour of the config, which is a type error at every JSX call site that names it.
    Codemod: npx astryx upgrade --codemod banner-collapsible-content
    It rewrites defaultIsExpanded to collapsible={{defaultIsOpen: true}} and drops defaultIsExpanded={false}, which is now the default. Banners that never set the prop are left alone.
    One case the codemod and the compiler both miss: a spread. defaultIsExpanded inside a props object is out of the transform's scope. A props object in a typed position still fails to compile — but an inferred one that is spread, <Banner {...args} />, does not, because TypeScript does not excess-property-check a spread. The prop then falls through to the DOM and the banner quietly starts collapsed. Grep for defaultIsExpanded after running the codemod and migrate any spread sites by hand.
  • Overlays share one dismissal stack, so a single Escape dismisses exactly one layer. Every overlay used to own its own Escape listener, which meant one press could close a popover and the Dialog hosting it, or a modal and the modal it was opened from. useLayerDismissal replaces that with a single stack: the stack owns one listener, routes each press to the top-most layer, and suppresses the browser's own close-watcher so nothing dismisses twice. A layer declares what it does with a press via escapeBehavior — close (default) or block, for a required Dialog that must swallow the press without closing so nothing behind it dismisses either. Fixes a Tooltip inside a Dialog closing the Dialog rather than the tip, and a HoverCard trigger swallowing Escape whenever it merely had focus. Dismissals the browser starts on its own — the Android back gesture, the platform close watcher — still close a Dialog, and follow the same top-most rule. An Escape that cancels an in-progress IME composition dismisses nothing: the stack claims that press so the browser raises no close request of its own, and a close request that arrives mid-composition anyway is declined, so a CJK user backing out of a half-formed character no longer loses the layer and everything typed into it. One behavior change worth knowing about if you listen for Escape yourself: the stack claims a press with preventDefault() but deliberately leaves propagation alone, so a keydown listener on window now sees an Escape that a focus-trapped layer used to stop — with defaultPrevented already true, which is how to tell the stack has acted on it. Top-most is resolved from React-tree nesting (which survives portals) rather than DOM containment alone. A layer's place in that order is keyed to the layer's identity rather than to each registration, so a prop change that re-registers it — a Dialog whose purpose flips while it is open — never promotes it above the layers opened over it. Controlled layers follow their control state: a controlled Tooltip or HoverCard stays on the stack and takes the press like any other layer, but answers it by calling onOpenChange(false) rather than hiding itself — whether it actually closes is the caller's update to make, exactly as it has always been for Dialog (#4881).
New Components
  • Allow MultiSelector count labels to be customized (#4032)
  • MultiSelector: rename the unreleased formatTriggerCount prop to formatValue and widen it to the whole trigger line. It now receives the selected items ({value, label}[], count available as .length) and formats the trigger for triggerDisplay="count" and "labels"; "badges" renders elements, so it is not used there. formatValue matches NumberInput and Slider, so the same idea has one name across the system. Defaults are unchanged when the prop is absent (#5377).
  • Promote Stepper and Step from the canary-only Lab package to Core. The stable package now ships their existing horizontal/vertical layouts, separated and on-track indicators, semantic status, density, and non-linear navigation, plus Core documentation and rendered examples. The default aria-label is now localized. Advancing one step now animates the connector. Every connector the four layouts draw — the separated bars and the on-track segments alike — grows its accent fill out of the segment's leading edge instead of swapping a background color, so moving forward reads as progress travelling the track. That one gesture is the only thing that animates: going back, jumping forward by more than one step, and mounting mid-flow all apply at once, as does any change under prefers-reduced-motion. Retreats are deliberately instant — run in reverse the same transition ends on a shrinking stub of accent, and a remnant still on the track reads as unfinished where the identical curve growing forward reads as arrived — and multi-step jumps are instant because a jump is a navigation rather than a progression, so sweeping a front across the crossed segments only makes the user sit out a journey they asked to skip. Where one span is drawn by several segments (the on-track layouts split a span between two steps, three when a content slot sits between them) the segments take abutting slices of the span's time and run linearly, so the fill reads as one line growing at a constant speed rather than pieces lighting in turn.
    Five visual fixes land with the promotion. Horizontal steps now divide the track evenly instead of sizing to their own labels, so every progress segment is the same width regardless of how long a step is named. Number indicators shrink from 20px to 16px to match the check, ring, and custom-icon indicators, so a step swapping its number for a check as it completes no longer nudges the label beside it. A step description now occupies a 16px box rather than a 24px one — it previously inherited the page's line box instead of applying its own leading, which opened an 8px gap under the label. A step's content slot now starts flush with the label above it at every density: the slot renders outside the density-padded label area, so it was hanging one pad short of it. And a vertical on-track step carrying content keeps its connector unbroken — the content renders below the row that draws the line, so the track used to split open around any step with content (#5201).
New Features
  • AspectRatio: emit ratio as a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass an aspect-ratio rule via xstyle (including under @media/@container conditions), and plain-CSS/Tailwind consumers override aspect-ratio from their own unlayered rules, which beat the astryx-base cascade layer regardless of specificity. The mixed-gallery template's hero now switches 3:1 to 3:2 when the grid stacks with a one-line override on a single element, replacing the duplicated hero markup the fixed inline ratio previously forced (#3883, closes #2798)
  • ChatMessageList: add an align prop for top-aligned message lists (#3933, closes #2572).
  • DateTimeInput: new timeOptionInterval prop adds a dropdown of preset times to the time field, at a cadence of 5 | 10 | 15 | 30 | 60 minutes (60 gives the 12 AM - 11 PM list). The field becomes an APG combobox over a listbox: click or Alt+ArrowDown opens it, ArrowUp/ArrowDown move the active option, Enter picks, Escape closes, and typing moves the highlight to the closest option without filtering the list. min/max trim the options on the boundary date. Style the popup through the date-time-input-time-listbox and date-time-input-time-option theme targets. Opt-in and additive: with timeOptionInterval omitted the time field keeps exactly its current behavior and gains no combobox semantics, so existing getByRole('combobox') queries still resolve to the date input. With the list closed the arrow keys keep stepping by timeIncrement (#4837).
  • Markdown: opt-in source ranges on parsed blocks parseMarkdown(source, {sourceRanges: true}) now gives every top-level block a range — {start, end}, the character offsets it occupies in the source that was passed in, with end exclusive — so a consumer holding that source can source.slice(range.start, range.end) for a block instead of reconstructing it from the node (or from the rendered DOM). Reconstruction is lossy in ways slicing is not: escapes, the exact emphasis and fence characters, heading depth beyond the clamp, and alignment all survive a slice unchanged.
    Off by default and absent unless asked for, so no existing node, snapshot or comparison changes.
    Two things the offsets get right that a naive implementation does not: link reference definitions are stripped before the block loop runs, and the ranges are reported against the string the caller passed rather than the stripped text; and parseMarkdownIncremental parses slices, so blocks report absolute offsets into the whole document as it streams — including a list whose halves arrived in separate chunks and were merged.
    A range covers a block's own lines verbatim, so slicing it and parsing the result gives the same node back.
    Blocks nested inside a list item or a blockquote carry no range: their children are parsed from text the parser reassembled with markers and > prefixes removed, so an offset into it would not address the document (#5290).
  • Table: let useTableSelection opt out of the checked-row accent wash The selection plugin paints checked rows by writing backgroundColor straight onto each <tr> from its row ref callback. An inline style outranks anything StyleX can layer on, so a product that wanted the row background for its own meaning had no way to reclaim it short of forking the plugin.
    hasRowHighlight turns the wash off. It defaults to true, so existing tables are untouched. Only the background is dropped — aria-selected is still set and removed exactly as before, since that is the half of the state screen readers read.
    tsx
    useTableSelection({...config, hasRowHighlight: false});
    ``` ([#5310](https://github.com/meta/astryx/pull/5310))
  • TabList: a strip that switches panels in place can now say so with role="tablist", and it speaks the WAI-ARIA tabs pattern — role="tablist" on the strip, role="tab" and aria-selected on the tabs, and aria-controls pointing at the panel each tab opens, from a new panelId prop on Tab. There is no new prop for the switch: TabList declares role?: AriaRole and reads it, the way LayoutHeader, LayoutContent and LayoutPanel already declare and document theirs. The keyboard behaviour the pattern asks for was already there: arrows move between tabs, Tab leaves the strip. Under the asserted role the strip takes only the horizontal arrows, leaving ArrowUp and ArrowDown to scroll the page. role already reached the DOM through {...restProps}, so a caller could pass role="tablist" and get a tablist whose children were still <button>s with aria-current — invalid markup, no aria-selected, and no warning. Reading the role turns that silent breakage into the correct behaviour; declaring it is what puts it in the type, the prop table and the docs.
    Nothing changes for a caller who passes no role: the strip is the <nav> landmark with aria-current it has always been. Any other role still passes through to the element untouched.
    Two development warnings come with the asserted role, and only with it. A tab with an href is a false statement inside a tablist, so the href is ignored and the warning says so. And a tab that controls nothing gets asked for a panelId — either that or an aria-controls you wrote yourself satisfies it, and a hand-written one is never overwritten. aria-controls is emitted only when you supply the id: pointing at a panel that does not exist is an invalid attribute value, which is worse than saying nothing. A menu or any other non-tab in a tablist strip is invalid markup, and warns too. The mirror case warns as well: a panelId on a strip that is not a tablist has no panel relationship to state, and is dropped (#5349).
  • TabList: a strip narrower than its tabs now scrolls instead of spilling out of its container. Every tab stays a tab — nothing is hidden behind a menu — the edges fade to show there is more, and pointers that can hover get arrow affordances; keyboard and screen-reader users reach every tab with the arrow keys, which scrolls the focused tab into view. The selected tab is scrolled back into view whenever it would be out of sight, including on mount and when the host changes value itself. The new overflow prop takes 'auto' (the default, which today always scrolls), 'scroll', or 'visible' to keep the old spill-out layout. Built on the existing useScrollOverflow hook, so there is no new measurement machinery and no Carousel in the tab strip — the documented Carousel recipe, which announced every tab as "slide N of M", is no longer needed and the stories now use the built-in behaviour. If you followed that recipe, nothing breaks: a Carousel still wrapping the tabs renders and behaves exactly as it did before, because its own scroll container absorbs the strip's, which then never overflows. Removing it is worth doing anyway — it drops the region/"slide N of M" wrapping from the accessibility tree, and the strip's own scrolling brings a tab that straddles the edge fully into view on focus, which the carousel does not (#5348).
Fixes
  • useTablePagination: with position='both' the two pagination <nav> landmarks now get distinct accessible names — "{label} (top)" above the table and "{label} (bottom)" below it (axe landmark-unique). Consumer-supplied label values are interpolated into both names; single-position labels are unchanged (#4692).
  • Table useTableRowExpansion: the chevron gutter's column header now carries a visually hidden localized name ("Row expansion", key @astryx.tableRowExpansion.columnHeader) instead of an empty <th> (axe empty-table-header, WCAG 1.3.1 best practice). The gutter stays visually blank (#5383).
  • Table useTableRowStatus: the status gutter's column header now carries a visually hidden localized name ("Row status", key @astryx.table.rowStatus.columnHeader) instead of an empty <th> (axe empty-table-header, WCAG 1.3.1 best practice). The gutter stays visually blank (#4693).
  • BottomSheet: a standalone sheet no longer dismisses when a CJK user presses Escape to cancel an in-progress IME composition. The browser fires that keydown before compositionend, so an Escape handler reading a bare event.key misread the composition cancel as a dismissal command and closed the sheet — losing whatever had been typed into a purpose="form" field inside it. The handler now early-returns on isImeKeyEvent, the same guard Dialog and BottomSheetSwitcher already carry, and claims the key first so the browser raises no close request of its own (#5322).
  • Breadcrumbs marks the current item with semibold weight, not colour alone. The current crumb was distinguished only by --color-text-primary against its siblings' --color-text-secondary, which fails WCAG 1.4.1 (use of colour) and leaves the current position invisible to anyone who cannot separate the two tones (#4605, closes #4421).
  • ButtonGroup: arrow keys pressed inside a member's open menu stay with that menu. A DropdownMenu renders its menu inline inside the group, so ArrowLeft and ArrowRight used to bubble to the group and move focus onto a sibling button while the menu was still open. The group's elevation is also reflected as data-elevation now, so a theme can target it (#5355).
  • ButtonGroup is a single tab stop. Its members now share one roving tab stop instead of taking one each, so a three-button group costs one Tab press rather than three. Arrow keys move between members along the orientation (flipped in RTL), Home/End jump to the ends, focus wraps, and disabled members are skipped. Two consequences worth knowing: a keyboard script or test that tabbed through a group member by member must use arrow keys now, and a member rendered as a link (href) joins the arrow order for the first time. (#5389)
  • Calendar (and DateInput, DateRangeInput, DateTimeInput) now opens on a month inside the min/max window instead of on today With no focusDate and no selected value, the calendar opened on today's month even when min/max excluded it — a 2019 audit window or a booking window that opens next spring rendered a grid where every day was disabled, and the only way in was clicking the prev/next arrows once per month.
    The initial month is now today clamped into the window: today when it is inside, otherwise whichever bound is nearest. An explicit focusDate or a selected value still wins, so nothing changes for callers that already say where to look. With numberOfMonths={2} a past window lands max in the right-hand pane, so neither pane is entirely out of bounds (#5306).
  • DateInput: clearing on touch no longer jumps the page to the top On the touch surface, tapping the clear (✕) threw the user to the top of the page. Clearing unmounts the clear button, and handleClear focused the field in that same task — on iOS Safari, focusing an element as the focused button is removed scrolls the whole document to 0. The focus handoff is now deferred past the unmount, which keeps the page where it was and still returns focus to the field.
    Measured on the iOS 26 simulator against the live docsite (DateInput — Clearable, page at scrollY 2055): synchronous focus → 0, deferred focus → 2055. preventScroll alone does not fix it; it is kept for the ordinary scroll-into-view nudge, which is unwanted for the same reason (#5350).
  • Clamp standard Dialog width to dynamic viewport space with token gutters, add safe-area/fullscreen sizing and fade-only fullscreen motion updates, add opt-in adaptive Dialog/BottomSheet recipes, and add explicit presentation comparison stories (#5352).
  • DropdownMenu: move the dropdown-menu-indicator-icon theme target onto the Icon element itself so a theme can restyle the submenu chevron's size and color directly. The loading branch no longer carries the target — its Spinner has its own astryx-spinner target, matching Selector, MultiSelector and ComplexSelector (#4743).
  • Chat: a token in a message bubble now sits on the line the way it does in the composer. ChatTokenizedText wraps each token in the same inline-flex / vertical-align: middle box ChatComposerInput uses, so a chip stops lifting off the text the moment the message is sent. Follows #5324, which fixed the composer half (#5402).
  • Chat: composer tokens no longer sit above surrounding text — vertical-align changed from baseline to middle, and ChatComposerTokenElement now uses a StyleX class instead of an inline style so consumers can override alignment without !important (#5324).
  • useFocusTrap: Tab is only cancelled when focus is actually inside the trapped container. An open layer whose focus legitimately sits outside it — a listbox popup anchored to its own input, as in DateTimeInput, Typeahead, Selector and MultiSelector — no longer swallows Tab for the whole page, so keyboard users move to the next control on the first press. A trapped surface with no tabbable controls and focus on a tabIndex={-1} panel still keeps Tab inside it (#5397).
  • mod hotkeys and Kbd resolve to Cmd on macOS again when client hints report a blank platform useHotkeys and Kbd both prefer navigator.userAgentData.platform and fall back to navigator.platform, but guarded the preference with 'platform' in uaData, which is true whenever the key exists at all. A build reporting platform: '' therefore committed to the client-hints branch and got false without ever reaching the fallback, so on macOS every mod combo listened for Ctrl and every <Kbd> drew Ctrl. Electron and other embedders that rewrite the app's user-agent identity ship exactly that. A blank platform is now treated as unknown and falls through (#5325).
  • Markdown streaming: parseMarkdownIncremental no longer throws away its settled blocks while a code fence is open, or when a chunk happens to end on a newline — both re-parsed the whole document, so a long streamed response got slower the longer it grew. Blocks rebuilt across a streamed 500-paragraph document: 126,756 → 1,869 (#5407).
  • Migrate core components from inline mergeRefs calls to stable useMergedRefs callbacks (#5267).
  • PowerSearch now applies menuWidth to the initial field and search menu without letting it shrink below the input width. Value menus shown after selecting a field are unchanged. (#5237)
  • PowerSearch: maxOperatorMenuItems now caps suggestions in string, string-list, and entity-list value typeaheads, including values inside nested filters (#5242).
  • PowerSearch: the edit popover now fits narrow viewports — its 400px minimum width yields to the screen width, and the filter row wraps instead of overflowing when long translated operator labels don't fit. An editor anchored near the screen edge now stays on its own side at the width available there, wrapping internally, instead of flipping across the anchor to keep 400px (#4768).
  • PowerSearch now groups fields in the browsing menu using each field's group value. Ungrouped fields appear first, while typed search results remain flat. (#5235)
  • PowerSearch now shows up to 1,000 configured fields when the search box is empty, instead of stopping at 10. Typed searches still show 10 ranked results by default; use maxSearchResults to change only that limit. (#5233)
  • Selector and MultiSelector no longer expose their {type: 'divider'} separators to assistive technology. role="listbox" only permits option/group children, but the divider previously rendered role="separator" as a direct child of the listbox (axe aria-required-children, impact critical). The divider is decorative and carries no information the options don't, so it's now hidden from the accessibility tree via aria-hidden, matching the pattern already used for section headings (#5107).
  • Keep merged refs stable across Avatar, Button, SideNav, TabList, and TopNav (#5429).
  • Add useMergedRefs and keep Text and Heading refs stable across rerenders (#5266).
  • Table: a plugin can suppress a body cell's content, and grouped rows use it to keep synthetic group headers out of your cell renderers (#5363) useTableGroupedRows injects section-header rows into the flattened data, and BaseTable evaluates every column's renderCell against every row. A renderer that keys a lookup off a field — STATUS_META[item.status].dot — was therefore handed a row that is not yours and threw, blanking the page the moment grouping was switched on. The header Proxy answering unknown fields with '' only ever rescued a renderer that prints a field; '' fails a lookup exactly as undefined does.
    BodyCellRenderProps gains isContentSuppressed?: boolean. A plugin sets it in transformBodyCell for a row whose cells it is about to replace wholesale in transformBodyRow, and the table renders that cell empty without calling the column's renderer or the default one. It is decided per cell at render time against the final column list, so it also covers columns other plugins contributed — whatever order the plugins were listed in.
  • TimeInput parses compact AM/PM values correctly (#4026)
  • Typeahead: Tab out of the field now moves focus to the next control. The result list is dismissed on the Tab keydown rather than from the blur that press produces — hiding a top-layer popover during the focusout makes Chrome abandon the in-flight focus move and drop focus to <body>, so the press appeared to do nothing. Selector and MultiSelector already dismissed on the keydown (#5400).
Documentation
  • document missing API contract props across Button, Toast, ContextMenu, MoreMenu, Selector, Link, and Dialog (#4315, part of #4163)
  • document missing props across complex components (MultiSelector, Tokenizer, PowerSearch, Typeahead, Layout, DropdownMenu, HoverCard, Tooltip, Link, Lightbox) (#4316, part of #4163)
  • document the missing components prop on Markdown (#4319, part of #4163)
  • document labelID and isGroupLabel props in Field (#4320, part of #4163)
  • document missing props across structural components (CodeBlock, Toolbar) (#4317, part of #4163)
  • Table: document the section components children mode requires Children mode stopped wrapping children in a <tbody> in #2098, but the docs still described the contract from before it. The children prop read "render TableRow/TableCell directly"; TableRow's own @example showed a row sitting in <Table> with no section around it; and TableHeader, TableBody, and TableFooter — public exports since that change — had no docs at all and were missing from Table's component list. A reader following the component's own documentation wrote <table><tr>, which is invalid HTML and mismatches on hydration.
    The three section components are now documented, listed on Table, and named in the children prop description, in a best practice, and in TableRow's example (#5278).
Other Changes
  • align?: 'top' | 'bottom' (default 'bottom'). 'bottom' keeps the existing behavior: a flex spacer fills free space so a short conversation sits just above the composer. 'top' omits the spacer so messages start at the top and grow downward — better for log-style or document-style lists.
  • Only changes the resting position of a non-full list. Once messages overflow the container the spacer collapses to zero in both modes, so ChatLayout auto-scroll-to-bottom behavior is unchanged.
  • Spinner: the ring is drawn in SVG instead of <canvas>. The arc and track take their colours from the cascade (currentColor for shade="inherit"), so nothing resolves a colour in JS: a colour change after mount now repaints the ring instead of leaving it stale until it remounts, and mounting spinners no longer costs a getComputedStyle each. Rings are pinned to the document timeline's origin, so spinners mounted at different times turn in phase. No API, geometry or theme-target change (#5408).
Contributors
Thanks to everyone who contributed to this release:

0.4.7

Fixes
  • BottomSheet: a non-modal sheet now colours the iOS 26 Safari toolbar strip with its own surface instead of letting the page show through behind the address bar (#5342).
  • BottomSheet: a tap inside the sheet is a tap, and the sheet leaves on an exit curve (#5326). Two defects, both of which read as "the sheet closes with no animation" — reported against the touch DateInput picker, which is a Bottom Sheet.
    A tap inside the sheet started a one-pixel drag. The sheet body carries the pull-to-dismiss handlers, and they promoted to a sheet drag on any downward movement. A finger is never still, so the pixel or two a tap drifts began a drag — and a live drag suppresses the panel's transition, correctly, because a dragged sheet must track the finger rather than lag it. The close that the tap triggered landed inside that window, so the sheet jumped to its closed position with no transition. Tapping the picker's Save button hit this every time; tapping the scrim never did, because the scrim is the dialog itself and arms no gesture. Promotion now needs 8px of travel — the conventional tap slop, well under what a deliberate pull covers in its first frames — in both the pointer and touch paths. The gesture's transition suppression is also scoped to a sheet that is open, so it cannot straddle an exit.
    The exit ran on the entrance's curve. --ease-standard is cubic-bezier(0.24, 1, 0.4, 1), a decelerate curve: it spends its speed immediately and coasts. Right for an entrance, wrong for an exit. Measured on device (iPhone, real Safari), a scrim tap put the sheet half off-screen in 59ms of the 410ms transition and 90% off in 163ms, with the dim gone before it — so the close was over before the eye could follow it. The closing state now carries an accelerating curve of its own, cubic-bezier(0.3, 0, 0.6, 0.6): away from rest, gathering speed, quickest as it leaves the screen, and moving within ~50ms so it reads as one departure rather than a hesitation and a snap. Only the curve changes — the exit keeps --duration-medium, the entrance's band, which is what keeps it legible under a theme that scales the motion scale down (neutral's medium is 300ms against the base 410ms).
    The scrim leaves with the sheet: while closing, the dim runs linear rather than the decelerate token. A fade covers no distance, so front-loading its progress just ends it early — the reasoning the touch date picker's surface swap already carries. BottomSheetSwitcher gets the same treatment when its flow closes; a handoff between two sheets is not a close and is unchanged.
  • useListFocus no longer swallows Escape when no onEscape was supplied. The hook called preventDefault() on every Escape — a habit inherited from the arrow keys, which share the handler and need it to suppress page scroll — so a list with nothing to dismiss still marked the key handled, and a surrounding layer that defers to defaultPrevented (a focus trap, a native popover) never got its turn. Escape is now consumed only when an onEscape is passed. Arrow, Home and End handling is unchanged (#5346). Behaviour change: AvatarGroup, ButtonGroup, Outline, Pagination, SegmentedControl, TabList and Toolbar pass no onEscape, so an Escape pressed inside one of them now reaches the surrounding layer and can dismiss it — the point of the fix, but a host that counted on the key stopping there will notice. NavHeadingMenu does the same when it renders without a menu close handler. Menus and flyouts that do pass onEscape are unaffected. patch, not [breaking]: the swallowing was never a contract — the hook documented Escape only as "custom callback", and no component advertised consuming the key.
  • TabList: the selected tab now carries aria-current="true" — ARIA's generic "current item within a set" — instead of aria-current="page". The strip is a <nav> and stays one, but it is used to switch views in place at least as often as it is used to navigate, and on those uses page asserted a page change that never happened. Assistive tech announced the selected tab as the current page even when nothing had navigated; it now announces it as the current item, which is true either way. A tab given an href still renders an anchor and still reads as a link — its current marker is just less specific than it was. No role changes and no new props. (#5347)
Contributors
Thanks to everyone who contributed to this release:

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](/components/Section) padding={6} paddingBlockStart={2}>…</[Section](/components/Section)> // tight top, 24px elsewhere
    <[Stack](/components/Stack) padding={4} paddingInlineEnd={0}>…</[Stack](/components/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](/components/Section) the matching --container-padding-* custom property moves with the prop, so bleed children ([Table](/components/Table), [Divider](/components/Divider), a nested [Section](/components/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](/components/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](/components/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](/components/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](/components/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](/components/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](/components/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](/components/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](/components/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](/components/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](/components/Section) inside an overlay took the page's padding instead of the theme default — 40px where 16px was meant. And [Lightbox](/components/Lightbox), [ContextMenu](/components/ContextMenu) and [HoverCard](/components/HoverCard) were never covered.
    The reset now lives in one place (overlayPaddingReset, exported from @astryxdesign/core/[Layout](/components/Layout)) instead of being hand-copied per overlay, and moved onto the [useLayer](/components/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](/components/DateInput), [DateTimeInput](/components/DateTimeInput), [DateRangeInput](/components/DateRangeInput), and [Calendar](/components/Calendar) now format and parse dates using the ambient [InternationalizationProvider](/components/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](/components/BottomSheet), [Dialog](/components/Dialog), [MobileNav](/components/MobileNav), [Popover](/components/Popover)) to prevent nested [Section](/components/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](/components/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](/components/Item) gets the axis, [SelectorOption](/components/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](/components/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](/components/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](/components/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](/components/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](/components/SyntaxTheme).tsx, the provider that actually needs it, so [SyntaxTheme](/components/SyntaxTheme) and [useSyntaxTheme](/components/useSyntaxTheme) keep their client boundary while the data exports resolve as data. No API change.
Contributors
Thanks to everyone who contributed to this release:

0.4.5

New Features
  • BottomSheet: snapPoints makes the drag-to-resize stops the host's choice. A stop is the sheet's visible height, written as a viewport fraction (0.5), a percentage ('50%'), or a px length ('320px') — matching height, where a bare number is also px and a string carries its unit. Fractions and percentages re-resolve when the viewport changes, so a sheet keeps the stop the user chose across a rotation, and swapping the points under a resting sheet re-anchors it the same way. A stop of a quarter of the sheet or less is a peek: it slides away rather than reflowing into a sliver, and thins the scrim. Taller stops are working surfaces, so they lay their content out and keep the scrim full — previously the shortest stop was always a peek, which would have thinned the backdrop of a half-height sheet (#5203). Behavior change, deliberate and not breaking: every sheet used to carry three built-in stops (14%, 50% and 92% of the viewport), so a drag could leave it resting somewhere the host never asked for. A sheet now opens and closes unless snapPoints says otherwise; pass snapPoints={[0.14, 0.5, 0.92]} to keep the old stops. No prop, type, or DOM output was removed or renamed, and swipe-to-dismiss, the height budgets, and mobile-keyboard accommodation are untouched.
  • Astryx ships translations for 28 more locales. packages/core/locales/ went from en and fr-FR to 30 files — Arabic, Catalan, Chinese (Simplified and Traditional), Czech, Danish, Dutch, Finnish, German, Greek, Hebrew, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese (Brazil and Portugal), Romanian, Russian, Serbian, Spanish, Swedish, Turkish, Ukrainian, Vietnamese and Afrikaans — covering every @astryx.* message the components announce or display (#5185). Nothing changes unless you ask for it: [InternationalizationProvider](/components/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).
Fixes
  • BottomSheet: a pull up from the scroll area now expands the sheet on iOS. Below the tallest detent, dragging up inside the content did nothing on a real device while the grab handle worked — the sheet took the gesture and then froze for the rest of the pull. iOS Safari raises PointerEvents for a finger under the same numeric id it puts in Touch.identifier, so the drag the touch path started was keyed to a live pointer: beginDrag captured that pointer, WebKit handed the capture straight back, and the lostpointercapture a millisecond later cancelled the drag. Touch-driven drags are now marked as such — they take no pointer capture, and lostpointercapture, pointercancel and pointermove for that same finger no longer cancel, end or double-drive them. Browsers that keep the two id spaces apart were never affected, which is why this only showed up on device (#5178).
  • Calendar weekday headers now use compact CLDR stand-alone-short names for the selected locale, while preserving the existing Su / Mo / Tu English labels.
  • Render generated id attributes on Markdown headings so Outline hash links scroll to their target. Heading slugs now come from parser helpers shared with parseOutlineFromMarkdown, and the components.heading override receives the generated id (#4765).
  • StatusDot: add an icon prop for API parity with [AvatarStatusDot](/components/AvatarStatusDot) — an optional ReactNode rendered centered in the 8px dot, painted from the dot's currentColor ink; booleans and empty renders are ignored so cond && <[Icon](/components/Icon) /> stays safe. Each variant now pairs its plate with a dedicated ink (--color-on-*, the Badge precedent) so a passed icon stays legible — notably the fixed dark on-warning ink on the yellow plate, where a light surface ink lands near 2:1. Per design review, the dot itself deliberately stays a plain colored signal: at 8px, built-in per-variant glyphs satisfy WCAG 1.4.1 on paper but are not genuinely readable, so making the status accessible in context (binary signal, visible label, icon, or an accessible alternative) is the builder's responsibility — see the StatusDot usage guidance (#4373).
  • [Table](/components/Table)'s row-expansion chevron now mirrors correctly under RTL. It previously rotated on expand with no RTL handling at all, so the directional glyph pointed the same way regardless of text direction, matching the pattern already used by TreeListItem's chevron (#5153).
Contributors
Thanks to everyone who contributed to this release: