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
variantaxis theme-extensible through aCardVariantMapinterface (#5551)CardVariantwas 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 nowkeyof CardVariantMap, an interface exported from@astryxdesign/core/Cardthat a theme build augments — the same shape Button, Badge, Section and the other extensible axes already ship.keyof CardVariantMapresolves to exactly the thirteen valuesCardVarianthad, so no existing call site changes. A variant a theme adds falls through to base styles and the theme's owncard['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 itsbackgroundColor. - CheckboxInput and Switch now name their own label as a theme target:
astryx-checkbox-labelandastryx-switch-label, alongside theastryx-field-labelevery label already carries. A theme could previously only reach oneastryx-field-labeltarget, 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) andastryx-checkbox-indicator-dash(the indeterminate bar) — mirroring the existingastryx-radio-indicator-dot. Both reflectsize. A theme restyling the mark itself (stroke weight, colour, the dash's proportions) previously had to reach it with.astryx-checkbox-indicator > svgand> span, which are element-and-order selectors that break silently on any restructure. Purely additive; no visual change. (#5426) - ComplexSelector:
onOpenChangereports every open and close of the popup — the trigger, the keyboard, a light dismiss, Escape, content callingclose(), or the imperative handle. Paired with the existinghandleRef, a consumer can drive and observe the surface without reading the shell's DOM. (#5211) - DateInput uses the platform date picker on touch, with
nativePickerto 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, andmin/maxcontinue 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:stepperDownwithout widening the requiredIconRegistrykeys (#5466)<Icon icon>,useIcon, anddefineTheme({icons})accept keys such asnumberInput:stepperDownandrichtext:bold; misspelled built-in names remain type errors. NumberInput keeps a compact centered Core fallback, while themes can override its steppers independently from the sharedchevronDownsemantic. OverflowListcan now hand its collapsed items to a menu you already render, viaonOverflowChange(overflowItems).overflowRendereronly 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 insideoverflowRenderermounts 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 directuseOverflowconsumer even when the available container width does not change. Keyed membership and order changes are re-measured beforeonOverflowChangereports 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; usingonOverflowChangealone adds nothing to the row. (#5199)- Selector and MultiSelector: configurable panel empty states via
emptyTextandemptySearchText, announced to screen readers as well as shown; a panel with no options now says so instead of rendering blank, and says nothing whileisLoading(#5462) - SideNavItem: new
actionsslot 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 inendContent;actionsis 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 — addsfocusOutlineProps.focusWithinFirstChildandfocusOutlineProps.suppressedfor that pairing. Supplied controls inherit the row's control size throughSizeContext, the waySideNavalready cascades one size to its footer icons, so an unsized icon button comes out the same box as the built-in toggle; an explicitsizestill wins. (#4988) (#5005) - Spinner: the ring's geometry and its two colors are now themeable. The
sizeandshadeprops keep their fixed enums; what each named value resolves to is now a theme's to set, through four public custom properties on thespinnertarget —--spinner-diameterand--spinner-stroke-widthunder a size variant,--spinner-colorand--spinner-track-colorunder a shade variant (or on the base target for all of them at once): (#5214)tsspinner: {'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,emandcalc()are resolved by the cascade into the radius and stroke the ring is drawn with, and colors acceptvar(),color-mix()andcurrentColor. A stroke width of0is 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 aninitial-valueinvalidates 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 importsSpinnerdrops 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 inlinewidth/heightwritten after the caller'sstyle, 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) andastryx-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 asizeaxis.sizemoves only the control's block padding (smandmdare empty;lgsetspaddingBlock), and that is the axis apaddingtranslation 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 isposition: 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 apaddingtranslation for the component, which is tracked separately. - Toast:
renderContenton theshowToastoptions replaces the content of that toast's card with your own layout. (#5428)tsxshowToast({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, itsastryx-toasttheme target, live-region role and auto-hide behavior. The renderer receives the message,endContent, resolved toast settings and adismisscallback.Custom content owns its complete layout and every control in it. Calldismissfrom 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 wrappinguseToast()and passingrenderContenton each call, while other toasts continue to use the ordinary Astryx layout and its translated, themeable dismissButton.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
finallydecline to clear the loading flag. The field kept reporting "Loading" to assistive technology until another search settled.hasCreateis 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. WithminQueryLength={3}, typingQAoffersCreate "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 tomaxMenuItems, so withhasCreatea 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)
Badgesetwhite-space: nowrapwith 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.Badgeuses no hooks and stays server-renderable.The ellipsis sits on an inner label span rather than the badge itself, becausetext-overflowneeds a block container and taking the root offinline-flexto 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'stitle— the same shapeBaseTablealready uses for a truncated header cell. That costs no measurement and no hook, soBadgestill renders the same on the server and stays usable in a server component. A richlabelis left alone rather than flattened to a guess.Two gaps remain, both needing runtime measurement, and both tracked in #5585: thetitleis set whether or not the label actually fits, and a nativetitleis 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 makesBadgea 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, andTypeaheadItemnow forward neutralaria-*,id,tabIndex, event-handler, anddata-*props to their rendered DOM element. Styling still merges throughmergeProps, contract-owned attributes retain precedence, and owned handlers compose throughcomposeEventHandlerswith the caller first.MetadataListItemtargets its wrapper<div>when stacked and its<dt>when inline. ATypeaheadItembacked by caller-supplieditem.elementremains unchanged and does not receive forwarded props because that value may not be a cloneable element. Buttonnow reflectselevationas a theme target. The prop selected between four StyleX style objects but was missing from the siblingthemeProps('button')call, sodata-elevationnever reached the DOM and no theme could style the axis — the same defect fixed onCardin #5491, and oneButtonGroupalready had right. A button inside aButtonGroupreportsnone, because the group owns the surface's elevation and the member paints flat. Every wrapper that forwardsButtonPropsthrough toButton—IconButton— picks the reflection up with it. (ToggleButtondoes not: its props extendBaseProps, notButtonProps, so it has noelevationto forward and keeps reportingnone.) 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
elevationas a theme target so a theme can reach it, and correct the documentedpaddingdefault (#5491)elevationpicked a style object but never reached the DOM, soastryx-cardexposeddata-variantand nothing for elevation and a theme could not style the four shadow tiers. It now ridesthemePropsalongsidevariant.Thepaddingprop documented4as 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 foureffectivePadding !== 4style 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:rootin@layer astryx-base, so nested themes inherit parent overrides andastryx theme buildmatches<Theme>whilegenerateThemeCSSkeeps 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
minRangeSpanis 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)andenv(safe-area-inset-right)are physical, but they were assigned straight topadding-inline-startandpadding-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. Themax()was applied to the fullscreen surface unconditionally, so it beat both apaddingprop and a theme'sdialog: {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*chaincontaineralready resolves, so it applies only when no padding is set anywhere. An explicit value,0included, 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
plainDateFormathelper continues to honor an explicitly suppliedcalendaroption 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-expandedreceive that state (#5419, #5501) The trigger now usesaria-haspopup="dialog",aria-controls, and a role-gatedaria-expanded;useHoverCardexposes the layeridand open state, whiledescribedByremains 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 declareBaseProps, andBasePropsdocuments thatdata-*,aria-*androlereach the element — but each destructured a fixed set of props and forwarded onlydata-testid, so anaria-labela 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 staysrole="document", the list keeps the explicitrole="list"that restores Safari/VoiceOver announcements, and a list rendering its own header keeps that association rather than one pointed elsewhere. Thearia-labelledbyfor that header is only written when the header exists — writingundefinedunconditionally 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.borderRadiusnow changes the rendered radius. Theastryx-popovertarget moves onto the popup surface — the box that paints background, radius and elevation — andusePopoverreads the registered--_popover-radiusthere instead of hardcoding--radius-container. Content padding moves with it, so a themedpaddingstill 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
idnow drives the trigger's whole identity, not just itsidattribute (#5561)Selectorgenerated its trigger id withuseId()and set it on the trigger button before spreading...rest, so a caller'sid— accepted throughBaseProps— replaced it on the button while the generated value stayed behind as the target of the listbox'saria-labelledbyand of theFieldlabel'shtmlFor. Passingidtherefore 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'sidwhen there is one, so the button, the listbox'saria-labelledby(both the plain and thehasSearchpanel) andField'sinputIDall name the same element. The trigger's ownidattribute 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 noidsupplied 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
Unknownsentinel as no answer, and lives in one place (#5394) Follow-up to #5325, which taughtuseHotkeysandKbdto fall through tonavigator.platformwhenuserAgentData.platformis blank.Unknownis 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 inutils/index.ts, which would publish it as API. - SideNavItem: the standalone expand/collapse toggle on a
collapsibleitem with anhreforonClicknow carries the box of asize="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:
collapsibleandresizableno 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 whenresizableis 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 (defaultIsCollapsedon both, or a controlledcollapsiblealongside collapse state onresizable)resizablewins and a dev warning names the conflicting keys.useResizablegains the standard controlled/uncontrolled pair,defaultIsCollapsedandisCollapsed, alongside the existingonCollapseChange: uncontrolled it owns collapse as before, controlled the prop wins andcollapse(),expand()and a drag past the threshold report through the callback instead of mutating. Persisted entries now store{size, isCollapsed}wheresizeis 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 thandefaultWidth; legacy entries still load, with a plain number read as a width whose collapse state is unknown and a plain0(written by the old collapse path) read as collapsed, so anyone already stuck with an invisible nav recovers without clearing localStorage.resizablecan now also carry collapse state on its own. Two notification changes ride along: with a single owner,collapsible.onCollapsedChangefires 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, andresize()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'spointerdownhandler callspreventDefault()and then focuses the thumb from script. Chromium treats that script focus as focus-visible, so:focus-visiblematched on mouse-down and every drag came with a 2px accent ring — measured in Chromium, not inferred.:focus-visiblestays the CSS condition; it is now narrowed by the existinginteractionModalityutility, 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-shadowtoken instead of a hardcodedlight-dark()tint, so a theme can retint it. (#5445) The tint waslight-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-punctuationborrowed--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-secondaryinstead (used for--color-syntax-commenttoo, 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).Addsscripts/check-syntax-punctuation-contrast.test.mjs, resolving each theme's--color-syntax-punctuation/--color-syntax-backgroundpair throughlight-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)
useTableGroupedRowspins its default heading and collapse control to the table's start edge.useTableSelectionnow 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
maxLinesclipped the text, both components rendered Astryx'sTooltipand set the nativetitleattribute 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.Thetitlegoes.Tooltipalready wiresaria-describedbyonto 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:2tooltips shown to the user, then1. - 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 rootbase-table→table(both named the same<table>element). AdefineThemekey that matches no target fails silently — no error, no warning, the rule never emits — so someone who readProgressBarand 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-labelledbyto therole="tree"element so a tree can be named (#5493)TreeListdestructured a fixed set of props with no rest spread, so everyBasePropsattribute (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 routesaria-label/aria-labelledbyonto the<ul role="tree">itself, so<TreeList aria-label="File tree">names the tree. When a visibleheaderis rendered, it keeps naming the tree (AT hears the same name the user sees); a consumer-suppliedaria-labelledbyonly applies on the headerless path. The contractrole="tree"is written after the rest spread so a consumer cannot displace it.
Documentation
useAnnounce,useTypeahead,useInteractiveRole,useLongPress,useInputStatusIcon,useDevWarninganduseIndicatorFocusRingare now discoverable. The CLI's hook index is built from the.doc.mjsfiles next to each hook, and these seven shipped without one; soastryx hook <name>answered "No hook named",astryx hookomitted them andastryx searchnever 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; foruseAnnouncethat means a hand-builtaria-liveregion, 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
collapsibleprop, and content can opt out of collapsing (#5255) Banner inferred its disclosure from its content: anychildrengot 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 — anddefaultIsExpandedwas the only knob, with no controlled mode.The whole axis is now oneboolean | CollapsibleConfigprop, following the boolean-or-config conventionSideNav.collapsibleset, and backed by the shareduseCollapsiblehook 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: controlledThe default is unchanged — a banner that never mentioneddefaultIsExpandedbehaves exactly as it did. The breaking part is the prop itself:defaultIsExpandedis 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-contentIt rewritesdefaultIsExpandedtocollapsible={{defaultIsOpen: true}}and dropsdefaultIsExpanded={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.defaultIsExpandedinside 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 fordefaultIsExpandedafter 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.
useLayerDismissalreplaces 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 viaescapeBehavior—close(default) orblock, for arequiredDialog 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 withpreventDefault()but deliberately leaves propagation alone, so akeydownlistener onwindownow sees an Escape that a focus-trapped layer used to stop — withdefaultPreventedalreadytrue, 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 whosepurposeflips while it is open — never promotes it above the layers opened over it. Controlled layers follow their control state: a controlledTooltiporHoverCardstays on the stack and takes the press like any other layer, but answers it by callingonOpenChange(false)rather than hiding itself — whether it actually closes is the caller's update to make, exactly as it has always been forDialog(#4881).
New Components
- Allow MultiSelector count labels to be customized (#4032)
- MultiSelector: rename the unreleased
formatTriggerCountprop toformatValueand widen it to the whole trigger line. It now receives the selected items ({value, label}[], count available as.length) and formats the trigger fortriggerDisplay="count"and"labels";"badges"renders elements, so it is not used there.formatValuematches NumberInput and Slider, so the same idea has one name across the system. Defaults are unchanged when the prop is absent (#5377). - Promote
StepperandStepfrom 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 defaultaria-labelis 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 underprefers-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
ratioas a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass anaspect-ratiorule viaxstyle(including under@media/@containerconditions), and plain-CSS/Tailwind consumers overrideaspect-ratiofrom their own unlayered rules, which beat theastryx-basecascade 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
alignprop for top-aligned message lists (#3933, closes #2572). - DateTimeInput: new
timeOptionIntervalprop adds a dropdown of preset times to the time field, at a cadence of5 | 10 | 15 | 30 | 60minutes (60gives the 12 AM - 11 PM list). The field becomes an APG combobox over alistbox: 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/maxtrim the options on the boundary date. Style the popup through thedate-time-input-time-listboxanddate-time-input-time-optiontheme targets. Opt-in and additive: withtimeOptionIntervalomitted the time field keeps exactly its current behavior and gains no combobox semantics, so existinggetByRole('combobox')queries still resolve to the date input. With the list closed the arrow keys keep stepping bytimeIncrement(#4837). - Markdown: opt-in source ranges on parsed blocks
parseMarkdown(source, {sourceRanges: true})now gives every top-level block arange—{start, end}, the character offsets it occupies in the source that was passed in, withendexclusive — so a consumer holding that source cansource.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; andparseMarkdownIncrementalparses 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
useTableSelectionopt out of the checked-row accent wash The selection plugin paints checked rows by writingbackgroundColorstraight 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.hasRowHighlightturns the wash off. It defaults totrue, so existing tables are untouched. Only the background is dropped —aria-selectedis still set and removed exactly as before, since that is the half of the state screen readers read.tsxuseTableSelection({...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"andaria-selectedon the tabs, andaria-controlspointing at the panel each tab opens, from a newpanelIdprop onTab. There is no new prop for the switch:TabListdeclaresrole?: AriaRoleand reads it, the wayLayoutHeader,LayoutContentandLayoutPanelalready 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.rolealready reached the DOM through{...restProps}, so a caller could passrole="tablist"and get a tablist whose children were still<button>s witharia-current— invalid markup, noaria-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 norole: the strip is the<nav>landmark witharia-currentit 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 anhrefis a false statement inside a tablist, so thehrefis ignored and the warning says so. And a tab that controls nothing gets asked for apanelId— either that or anaria-controlsyou wrote yourself satisfies it, and a hand-written one is never overwritten.aria-controlsis 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: apanelIdon 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
valueitself. The newoverflowprop takes'auto'(the default, which today always scrolls),'scroll', or'visible'to keep the old spill-out layout. Built on the existinguseScrollOverflowhook, so there is no new measurement machinery and noCarouselin 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: aCarouselstill 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 theregion/"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-suppliedlabelvalues 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 bareevent.keymisread the composition cancel as a dismissal command and closed the sheet — losing whatever had been typed into apurpose="form"field inside it. The handler now early-returns onisImeKeyEvent, the same guardDialogandBottomSheetSwitcheralready carry, and claims the key first so the browser raises no close request of its own (#5322). Breadcrumbsmarks the current item with semibold weight, not colour alone. The current crumb was distinguished only by--color-text-primaryagainst 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
elevationis also reflected asdata-elevationnow, 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
focusDateand no selected value, the calendar opened on today's month even whenmin/maxexcluded 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 explicitfocusDateor a selected value still wins, so nothing changes for callers that already say where to look. WithnumberOfMonths={2}a past window landsmaxin 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
handleClearfocused 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.preventScrollalone 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-icontheme 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 — itsSpinnerhas its ownastryx-spinnertarget, 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.
ChatTokenizedTextwraps each token in the sameinline-flex/vertical-align: middleboxChatComposerInputuses, 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-alignchanged frombaselinetomiddle, andChatComposerTokenElementnow 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). modhotkeys andKbdresolve to Cmd on macOS again when client hints report a blank platformuseHotkeysandKbdboth prefernavigator.userAgentData.platformand fall back tonavigator.platform, but guarded the preference with'platform' in uaData, which is true whenever the key exists at all. A build reportingplatform: ''therefore committed to the client-hints branch and gotfalsewithout ever reaching the fallback, so on macOS everymodcombo 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:
parseMarkdownIncrementalno 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
menuWidthto 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:
maxOperatorMenuItemsnow 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
groupvalue. 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
maxSearchResultsto change only that limit. (#5233) SelectorandMultiSelectorno longer expose their{type: 'divider'}separators to assistive technology.role="listbox"only permitsoption/groupchildren, but the divider previously renderedrole="separator"as a direct child of the listbox (axearia-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 viaaria-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)
useTableGroupedRowsinjects section-header rows into the flattened data, andBaseTableevaluates every column'srenderCellagainst 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 asundefineddoes.BodyCellRenderPropsgainsisContentSuppressed?: boolean. A plugin sets it intransformBodyCellfor a row whose cells it is about to replace wholesale intransformBodyRow, 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. Thechildrenprop read "render TableRow/TableCell directly";TableRow's own@exampleshowed a row sitting in<Table>with no section around it; andTableHeader,TableBody, andTableFooter— public exports since that change — had no docs at all and were missing fromTable'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 onTable, and named in thechildrenprop description, in a best practice, and inTableRow'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 (currentColorforshade="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 agetComputedStyleeach. 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-standardiscubic-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 runslinearrather 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.BottomSheetSwitchergets the same treatment when its flow closes; a handoff between two sheets is not a close and is unchanged. useListFocusno longer swallows Escape when noonEscapewas supplied. The hook calledpreventDefault()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 todefaultPrevented(a focus trap, a native popover) never got its turn. Escape is now consumed only when anonEscapeis passed. Arrow, Home and End handling is unchanged (#5346). Behaviour change:AvatarGroup,ButtonGroup,Outline,Pagination,SegmentedControl,TabListandToolbarpass noonEscape, 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.NavHeadingMenudoes the same when it renders without a menu close handler. Menus and flyouts that do passonEscapeare 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 ofaria-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 usespageasserted 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 anhrefstill 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)
DateInputhas 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.pointermeans the PRIMARY device, so a touchscreen laptop reportsfineand 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 —DateInputPropsis 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 adata-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 apointerdownon 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
useLocaleanduseCollatorfor provider-backed formatting and comparison (#5194) - RadioListItem: the
radio-list-itemrow theme target now carriessize,selected, anddisabledstate variants (matchingmulti-selector-option), so themes can style selected or disabled rows (#5143). - RadioListItem: the
radio-list-itemtheme target now rides the painting row element (converging withlist-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(withHStack/VStack) andCenteraccept a padding prop for each of the four edges —paddingBlockStart,paddingBlockEnd,paddingInlineStartandpaddingInlineEnd— so an edge can take its own spacing step without anxstyleescape hatch.Sectionalso gains thepaddingInlineaxis prop it was missing, so all three components now expose the same seven-prop set (#5224). Each prop takes the same spacing scale aspadding, and resolution is most-specific-wins, per edge:edge prop → axis prop (paddingInline/paddingBlock) →paddingAn 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 edgeThe inline props are logical, sopaddingInlineStartis 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,paddingInlineandpaddingBlockbehave exactly as before, and their generated class output is unchanged.- Selector: add the
selector-option-rowtheme target on the dropdown option row, carryingsizeplusselected/disabledstate — so a theme can restyle row padding and density directly (mirroringmulti-selector-option), instead of reaching the barerole="option"element with a structural selector (#5179). - MediaTheme: add
mode="auto"andmode="off"(#5299) A theme is free to define--color-background-invertedas something that is not inverted — and a component that hardcodesmode="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-lightreads 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 newmode="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 abackground-image, whose pixels need sampling (see[useImageMode](/components/useImageMode)) rather than a computed style —autouses the newfallbackprop instead of guessing.Toast now usesmode="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: themouseentera 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 atouchTriggerprop, and what the trigger DOES decides the default. A trigger that performs an action — a button, a link, a form control — keeps its tap underauto: 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.tapandnonestate the choice outright;tapis 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-visibleby design.[fix] InfoTip (lab): opts intotouchTrigger="tap". Its trigger is a real button, so theautorule 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 — therole="img"root prunes descendant semantics, so composing it in is the only route to assistive tech (WCAG 4.1.2). Readinglabeloff a directly-passed element still works and still resolves on the first render. An interactive avatar (href/onClick) with noname/altwarns 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. Derivedrole/aria-label/aria-hiddennow 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 wasdisplay: flexon 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 isinline-flexnow; inside a group nothing changes, because a flex item is blockified either way.Its label font size was a baresize * 0.35, which computes 7px atxsmand 8.4px atsm. 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 atxsmis#bebebeon a#f0f0f0field, a contrast of 1.63:1 where 4.5:1 is required. The size now floors at the--text-supporting-sizerole token and scales proportionally above it, somdand 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 negativecountrendered the string+-3and announced "-3 more"; since the documented shape for the prop istotal - 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 nomaxprop. 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, andsizenow says that the group's value wins over each child avatar's ownsize, including when the group leaves it at the default. - Blockquote: the
citeattribution renders as a bare<cite>instead of being wrapped in a<footer>, which was becoming acontentinfodocument landmark. Also guards the slot withisRenderable, socite={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-highdrop 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-borderhairline 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: mandatoryis 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. Everycursorin 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 behindpointer-events: noneare unchanged: the pointer never reaches them, so their cursor comes from an ancestor — which is why the guarantee isdefaultrather 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-
:hoverin core and lab, and every:hovera 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
::afteroverlay 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 theastryx-input-clear-icontheme 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: nonewhile 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-stylesupplies it, for the drawer's transform and for the::backdrop's opacity. Second, the dialog clipped the off-screen drawer withoverflow: 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-styleentry transition for its descendants in Chromium — the transition ticks in the CSSOM while every painted frame shows the end value.overflow: clipclips 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-mediumand both collapsing underprefers-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-inputpadding left the steppers short of the field edges (a gap top and bottom), and a themedborderRadiusrounded 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 singlepaddingBlockStart— and both the wrapper and the column read the resulting per-side--astryx-number-input-padding-*tokens; an asymmetricpaddingBlock: 4px 12pxis cancelled correctly at each edge. A themednumber-inputborderRadius 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 toinitialso readers fall through to their own default rather than losing their padding.Section's padding propagation moved from the public--astryx-section-paddingtoken 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-paddingremains the public token and still reaches inside overlays. - Theming: a physical
paddingTop/paddingBottomnow reaches the container padding expansion, socard,dialog,sectionandnumber-inputtrack 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'pluspaddingTop: '14px'published 10px in the tokens while the element painted 14px on top.padding-topandpadding-bottomARE the block edges in every horizontal writing mode, so this normalization assumes no direction.paddingLeft/paddingRightare 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(backingformatSharedDate) previously calledIntl.DateTimeFormat(undefined, ...), anddateParser's day/month disambiguation heuristic for ambiguous numeric input (e.g.3/4/2026) calledIntl.DateTimeFormat()with no locale at all, so a tree wrapped in a non-Englishlocalestill 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: stablefor the duration of the lock, which keepsposition: fixedchrome (sticky headers, toast viewports) still as well as in-flow content. Pages with no space-taking scrollbar, and pages that already setscrollbar-gutterthemselves, are left alone. Engines withoutscrollbar-guttersupport 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:
SelectorOptionDatagainsdescription, 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 theoptionsprop — the data type carried onlyvalue/label/disabled/icon— so consumers kept a side map of descriptions keyed by value and re-rendered the row throughrenderOption.descriptionnow sits on the option data andDefaultOptionforwards it. On the trigger, the selected option's owniconrenders in the closed state (startIconstill wins when set, so a pinned field icon never doubles up), which retires the app-sidestartIcon={value === 'x' ? … : …}mirroring of state the component already knows.renderValueis the seam for drawing the selection yourself — the description included (#5202). [feat] Item: newlayoutprop —'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 wheneverrenderValuewas 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 thesizeprop 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 asize="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)withorientation="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/syntaxis 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 — includingdracula,oneLight,allSyntaxPresets,syntaxTokenDefaultsanddefineSyntaxTheme, 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, sopreset.tokenswasundefinedand 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:
snapPointsmakes 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') — matchingheight, 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 unlesssnapPointssays otherwise; passsnapPoints={[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 fromenandfr-FRto 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/*.jsonexport. An app that already passes alocalenow 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
maxRangeSpanandminRangeSpanto 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'onlyisRequiredfields show one; under'required'onlyisOptionalfields do; a field that restates the default shows nothing. Under'required'the unmarked fields also exposearia-requiredso screen readers match what sighted users see — resolved onaria-requiredonly, never the nativerequiredattribute. Unset keeps today's per-field behavior (#4791). - Add
astryx-input-clear-buttontheme 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:beginDragcaptured that pointer, WebKit handed the capture straight back, and thelostpointercapturea millisecond later cancelled the drag. Touch-driven drags are now marked as such — they take no pointer capture, andlostpointercapture,pointercancelandpointermovefor 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/TuEnglish 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
iconprop for API parity with[AvatarStatusDot](/components/AvatarStatusDot)— an optional ReactNode rendered centered in the 8px dot, painted from the dot'scurrentColorink; booleans and empty renders are ignored socond && <[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 byTreeListItem's chevron (#5153).
Contributors
Thanks to everyone who contributed to this release: