What's New
Release notes and changelog for all packages.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)anduseSyntaxThemekeep 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:
0.4.4
New Components
- Promote
[BottomSheet](/components/BottomSheet)and[BottomSheetSwitcher](/components/BottomSheetSwitcher)from the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
New Features
astryx template --cdnwrites a working no-build-step CDN starter page (#5068). A CDN starter is a template, so it joins the template family beside--skeletonrather than claiming a top-level command. It is a flag and not the positionalastryx template cdnbecause the positional resolves against everythingdiscoverAll()finds, where acdnid would shadow a discovered template.cdn.template.htmlloads Astryx from jsDelivr and esm.sh with no bundler, no install and no build step, with every CDN URL pinned to the Astryx version you have installed — an unpinned CDN URL resolves to whatever is latest and is cached hard, so a page written today breaks tomorrow without being edited. An existing file is never clobbered;--overwritereplaces it, and--jsonreturns the receipt.The annotations are the things that are load-bearing and silent when missing:?external=react,react-dom(without it esm.sh bundles a second React and every hook throwsCannot read properties of null (reading 'useState')),react/jsx-runtimein the import map (the published bundle imports it; omitting it fails the page withFailed to resolve module specifier), and afont-familyonbody(nothing in the stylesheets sets a document font, so[Button](/components/Button)— which isfont: inherit— otherwise renders its label in the browser's default serif).Three more lessons came out of building a real app on it. The page now<link>s the theme's webfont from Google Fonts, because the theme names Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in<[Theme](/components/Theme) theme={neutralTheme} mode="system">, so light and dark follow the OS — thedata-astryx-themeattribute alone scopes the stylesheet but cannot switch modes. And#root:emptycarries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup ishtm, with a comment saying it is optional andcreateElementis the dependency-free alternative.A recipe that is only read is a recipe that is only assumed to work, so CI renders it:.github/scripts/cdn-template-smoke-test.mjsscaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.- DateTimeInput: expose
date-time-input-toggle-icon(calendar glyph, with open/closedstate) anddate-time-input-clock-icon(leading time glyph) theme targets, so a theme can size and color the leading icons — matching thedate-input-toggle-iconseam DateInput already offers (#5148). defineTheme:color.accentaccepts a[light, dark]tuple (#2279)ColorScaleConfig.accentnow takes either a single hex or a[light, dark]tuple, matchingTokenValue. With a tuple,expandColorScalederives the light half of every generatedlight-dark()pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of thetokens['--color-accent']workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence betweencolorandtokensfor accent-derived values:tokensentries win token by token, thevar(--color-accent)reference tokens follow a--color-accentoverride at runtime, and the baked--color-on-accentstays derived from thecolor.accentseed.
Fixes
- Banner:
endContentwraps to its own row on a narrow header instead of squeezing the title to one word per line (#5116). - BottomSheet: a swipe that scrolls to the end of the sheet's content and keeps pulling now expands the sheet, instead of stopping dead at the last line. The handoff used to be decided once, when the finger landed: a gesture that started mid-content stayed a scroll for its whole life, so the natural motion — swipe up through the list, reach the bottom, keep pulling — never reached the sheet. Reaching the end of the content is now enough. The sheet is anchored at the point where the content ran out, so only the travel past it moves the sheet, and the pull is left to the content when the finger comes back down or when there is no taller detent to expand into (#5172).
- BottomSheet: an upward pull at the bottom of scrolled content no longer hijacks the gesture when the sheet is already fully expanded. It used to hand off to a sheet drag with nowhere to expand to, producing a rubber-band the release threw straight back, and — because the handoff swallows the rest of the gesture — leaving the content unscrollable until the finger lifted, so dragging back down collapsed the sheet instead of scrolling. The bottom edge now hands off only when a taller detent exists (#5161).
- BottomSheet: a sheet resting at a detent now follows the viewport. Its detents were resolved to pixels at gesture time and never revisited, so rotating the device or resizing the window left the sheet frozen at the old geometry — a half-height sheet covering three quarters of a shorter window, and a peek detent whose slide-down could exceed the new viewport entirely, leaving a modal dialog on screen with no sheet in it. Snap fractions are also read from the layout viewport now, so the mobile keyboard no longer moves the detents out from under the sheet it is measuring (#5159).
- BottomSheet keeps the page still when the mobile keyboard reveals a field the browser focused itself (#5158)
- Screen-reader announcements are now localizable. MultiSelector, Selector, Typeahead, FileInput, Tokenizer, and Lightbox spoke several live-region messages in hardcoded English — selection and result counts, file selections, token add/remove, and gallery position — so they stayed English under an
[InternationalizationProvider](/components/InternationalizationProvider). They now resolve through the message catalog like the rest of the UI, and the counts use ICU plurals instead of appending an English "s", so locales with other plural rules read correctly (#4920). - The editable text fields in
[Selector](/components/Selector),[MultiSelector](/components/MultiSelector),[Typeahead](/components/Typeahead),[DateInput](/components/DateInput),[DateTimeInput](/components/DateTimeInput),[TimeInput](/components/TimeInput), and[NumberInput](/components/NumberInput)no longer misinterpret the keydown that commits or cancels an IME composition (Korean/Japanese/Chinese input) as a command. Previously a composing Enter would select/toggle the highlighted option or commit a typed date, a composing Escape would exit[Typeahead](/components/Typeahead)'s edit mode, and a composing arrow would step a time or number value — all before the composition finished. Each field now lets the IME finish first, matching the guard already in place for[BaseTypeahead](/components/BaseTypeahead)and the Chat composer (#4908). - MobileNav: keep the drawer rendered until the native dialog has actually closed (#4290)
displaywas driven by theisOpenprop, which flips during the commit, whiledialog.close()only ran afterwards from an effect — so every close calledclose()on a dialog that was alreadydisplay: nonebut still open and still in the top layer, and an open modal dialog blocks the whole document whether or not it is rendered. Safari 26.1 never un-blocked it, leaving the page inert with no JavaScript error.displaynow takes part in the transition withtransition-behavior: allow-discrete, including when React's<Activity mode="hidden">hides the drawer inside AppShell, and the unmount close moves into its own effect so the deferred close is no longer cut off by its own cleanup. The close delay is derived from the hold in effect rather than assumed, because that hold is--duration-medium— a theme value, which the shipped y2k theme sets to exactly the 250ms the delay used to hard-code. [Switch](/components/Switch)withisLabelHiddenno longer reserves the label gap. The hidden label issr-only, but its wrapper stayed a flex item, so the row still painted the 8px gap beside it: the field box measured 8px wider than the track it contains, and a hidden-label switch stopped 8px inside the edge every neighbouring control lined up on. The gap now collapses with the label, so the field is exactly as wide as the painted track — matching[CheckboxInput](/components/CheckboxInput), which already did this (#5112).- Inputs (
statusVariant="tooltip"): the focusable status button now opens its tooltip on hover inside[TextArea](/components/TextArea), whose absolutely-positioned trailing slot ispointer-events: none. Keyboard focus already worked; pointer hover did not (#5147).
Other Changes
- Clear the mechanically fixable ESLint suppressions from the Bottom Sheet promotion:
[BottomSheet](/components/BottomSheet)and[BottomSheetSwitcher](/components/BottomSheetSwitcher)now use the React 19 context APIs (<Context>as provider,use()), the panel drops its duplicate body-element ref in favor of the one the gesture hook already tracks, anduseSheetGesturesreadsprefers-reduced-motionthrough the shared[useMediaQuery](/components/useMediaQuery)subscription so an open sheet follows a preference change (#5155). - Remove the UMD bundle — it could not work with any React this package supports (#5068).
dist/astryx.umd.jsis no longer built or published, and with it go theunpkgandjsdelivrpackage fields, the./astryx.umd.jsexport and thebuild:umdstep.Nobody has a migration to make, because there was no working configuration to migrate from. The bundle binds Astryx towindow.Reactandwindow.ReactDOM, and React 19 does not ship a build that defines them: "UMD builds removed: To load React 19 with a script tag, we recommend using an ESM-based CDN such as esm.sh."https://unpkg.com/react@19.2.0/umd/react.production.min.jsis a 404 where 18.3.1 is a 200. OurpeerDependenciesarereact >= 19.0.0, so every supported React is one without a global for the bundle to bind to — it documented a path that never had an entrance.If you were loading it with an older React anyway, load the same components as modules instead: an import map forreact,react/jsx-runtime,react-dom,react-dom/clientand@astryxdesign/core(pinned, with?external=react,react-dom), then one<script type="module">.astryx template --cdnwrites that page for you, pinned to your installed version and annotated; the recipe is also in the core README under "No build step (CDN)". isImeKeyEvent— the guard that stops an IME composition keystroke being read as a command — now lives at@astryxdesign/core/utilsalongside the other pure helpers, with the reasoning for its two signals written down in one place. It stays exported from@astryxdesign/core/hooksfor this release but is deprecated there: it is a plain predicate, not a hook, and that barrel is a'use client'boundary, so importing it fromhookspulls a server-safe function onto a client path. Move imports to@astryxdesign/core/utils; thehooksre-export will be removed in an upcoming major (#4907).
Contributors
Thanks to everyone who contributed to this release: