What's New
Release notes and changelog for all packages.0.1.5
New Features
- AspectRatio: add a
fitprop ('cover' | 'contain' | 'center') so the component sizes and positions its child instead of every consumer hand-writingwidth/height/objectFiton the child.cover/containship as zero-specificity baseline rules inreset.csskeyed on adata-astryx-aspect-ratio-overridemarker the component sets on the child's direct parent (direct-child selectors, no dependence on internal structure or the theming surface), so a child's own styles always win and self-sized children are unchanged;centercenters the child at its natural size from the component's wrapper. Whenfitis omitted the child is left unstyled, preserving the existing contract (#2753) - CodeBlock: new
syntaxThemeprop for per-instance syntax theme overrides. Shorthand for wrapping a single block in<SyntaxTheme theme={...}>— accepts a preset from@astryxdesign/core/theme/syntaxor a theme created withdefineSyntaxTheme()(#3360). - CollapsibleGroup: add a
hasDividersprop (boolean, defaultfalse) so FAQ-style accordions get built-in row hairlines instead of hand-rolled borders, plus adensityprop ('compact' | 'balanced' | 'spacious') controlling row padding. When dividers are enabled the group renders a wrapper div (astryx-collapsible-group) and items default to'balanced'density; without dividers the group keeps its DOM-less contract and existing renders are unchanged. Borders use the themed--border-width/--color-bordertokens, and nested collapsibles never inherit row chrome (#3487). - New
incident-consolepage template: an on-call incident response console demonstrating the frame-first tracker archetype — grouped dense incident rows (StatusDot severity, Token state), PowerSearch filtering, status segmented control, and a resizable inspector panel with metadata and timeline. Adds theTools - Incident Consoletemplate category. - useLayer: new
positioning: 'custom'context render option for consumers that author their own position styles (explicitanchor()insets,anchor-size()covers). Keeps the popover behavior andposition-anchorwiring but derives no position styles fromplacement/alignment— including the automatic RTL mirroring, which becomes the consumer's responsibility (#3389). - New
messaging-shellpage template: Slack-style column frame (rail | sidebar | stream | thread panel) built on the Chat component family — dense rows, zero cards. Adds theShell - Messagingtemplate category. - Pagination: the
dotsvariant is now keyboard navigable via the shared useListFocus primitive. With a dot focused, Left/Right arrows move between dots and Home/End jump to the first/last, the active page follows focus (roving tabindex), and Up/Down are left to the browser so vertical scrolling is unaffected. (#3681) - Switch: rename the labelSpacing
"default"value to"hug";"default"keeps working as a deprecated alias. Runastryx upgradeto migrate call sites automatically. (#2889) - Add
useHotkeyshook for global keyboard shortcuts. Registers one windowkeydownlistener per hook instance with handlers kept in a ref (re-renders never re-subscribe). Combos like'mod+k'or'escape'—modmaps to ⌘ on Apple platforms (same detection as Kbd) and Ctrl elsewhere. Skips typing targets (input/textarea/select/contenteditable) unlessallowInInputs, skipsdefaultPreventedevents, and callspreventDefault()on match. SSR-safe.
Fixes
- Emit derived accent tokens as var(--color-accent) references (#3495)
Generated themes now emit
--color-text-accentand--color-icon-accentasvar(--color-accent)and--color-accent-mutedascolor-mix()over the same reference, instead of baking resolved hex literals. Overriding--color-accenton any scope re-accents the whole subtree at runtime — no second theme build, no per-token overrides.--color-on-accentstays resolved because it is a contrast computation CSS cannot express. - adjustTime guards non-finite deltas and wraps negatives in O(1) (#3583) A non-finite deltaMinutes previously spun the wrap-around loop forever (-Infinity — tab freeze) or produced the corrupt string "NaN:NaN" (NaN) that could be committed into consumer form state through DateTimeInput's timeIncrement path. Non-finite deltas now return the input time unchanged, and the negative wrap-around uses double-modulo instead of a loop.
- Forward rest props on AlertDialog and AppShell so consumer
data-*,aria-*, andidattributes reach the DOM (#3876) - Wrap CommandPalette search updates in
startTransitionto resolve a React 19 warning (#3815) - Derive DropdownMenuItem escape hatches from BaseProps so it accepts
xstyle,className, andstyle(#3687) - Order rest spread before explicit ARIA props on Item and InputGroup so consumer-set ARIA attributes are no longer clobbered (#3751)
- Avatar: retry a changed src/fallbackSrc after a load error
A failed image load latched a boolean error flag that never reset, so updating
src(orfallbackSrc) to a valid URL kept rendering the initials fallback forever. The error state now tracks the exact URL that failed, so a changed source gets a fresh load attempt. - Banner: the expand/collapse toggle is now linked to its content region via
aria-controls, completing the disclosure pattern (the toggle already exposedaria-expanded). (#3719) - Calendar: mark today's date cell with
aria-current="date". Previously "today" was conveyed only visually, so screen-reader users could not identify the current date (WAI-ARIA date-picker pattern). (#3708) - Calendar: move aria-selected from the day button onto its gridcell wrapper. A plain button (implicit role "button") does not permit aria-selected, which tripped the axe aria-allowed-attr rule; the selection state belongs on the gridcell role in an ARIA grid. (#3343)
- Calendar / DateInput / DateTimeInput: defensively clamp
numberOfMonthsto its1 | 2type at runtime. Out-of-range values (e.g.0rendered nothing,1000locked the page up inArray.from({length})) fall back to a single month. DateInput and DateTimeInput inherit the guard since they forward the prop to<Calendar>(#2704) - Calendar: month navigation chevrons now mirror under
dir="rtl"so "Previous month" points outward (visually right) and "Next month" points left, instead of both pointing inward at the month label. The mirror is a CSS-only StyleX conditional transform keyed on thedirattribute; DOM order, labels, and handlers are unchanged. Also fixes the embedded calendars in DateInput, DateRangeInput, and DateTimeInput (#3388). - Card: draw the
defaultvariant's border inside its padding and drop the invisible border from the other variants, so a card's total inset (border + padding) matches the spacing token exactly instead of being 1px larger on every side. (#3712) - Carousel: make the horizontal scroll container keyboard-focusable (
tabIndex={0}) so keyboard-only users can scroll it with arrow keys. Previously the scrollable region had no keyboard access (axe: scrollable-region-focusable). (#3343) - Chat components forward pass-through props (data-, aria-, id) to the DOM
ChatDictationButton,ChatLayoutScrollButton,ChatMessageMetadata,ChatSystemMessage, andChatTokenizedTextdeclaredBasePropsbut silently droppeddata-*,aria-*, andid: they never captured...restnor spread it onto their rendered element. They now capture...restand spread it onto their primary element after the merged className/style, with any component-owned attribute (e.g.role) set afterward so it still wins. - Chat: tool-call rows and the tool-calls group header now expose complete disclosure semantics — expandable call rows announce
aria-expandedand reference their detail panel viaaria-controls, and the group header references its content region. Previously an expandable call row was announced as a plain button with no indication it opens anything. (#3720) - ChatComposerInput preserves composer submit with child onChange (#2330)
- CheckboxInput now forwards rest props (including
data-testid) to the underlying<input>. Previously the component used a closed destructuring list with no...restcapture, so any prop not explicitly named —data-testid, otherdata-*attributes, etc. — was silently dropped despiteCheckboxInputProps(viaBaseProps) typing them as valid. Every sibling input component (TextInput, Selector, Slider, Button, Badge) already forwards rest props; CheckboxInput was the sole outlier. Rest is spread before the component's own named attributes on the<input>, so it cannot overridechecked,disabled,type, or any other explicitly-set prop. - ClickableCard: remove the faint hover "ring" on borderless variants (everything except
default) by dropping their invisible border. Thedefaultvariant now draws its border inside the padding so outer dimensions stay identical across variants, and its border color emphasizes on hover. (#3712) - CodeBlock: announce "Copied" via a polite live region when the copy button is used. Previously success was signalled only by swapping the button's
aria-label, which screen readers don't reliably announce. (#3709) - CodeBlock: restart the copied-indicator timer on rapid re-copy Each copy click armed an independent 2s reset timer, so copying again within the window let the first click's timer revert the "Copied" indicator early. The timer now restarts on every copy and is cleared on unmount.
- CodeBlock: complete the collapsible header's disclosure pattern. It now shows the standard accent focus ring on
:focus-visible— previously it defined no focus style and fell back to the browser's default outline, unlike the system's other disclosure controls (Collapsible, TabMenu) — and links to the code region it shows/hides viaaria-controls(the header already exposedaria-expanded). The region stays mounted when collapsed (CSS grid animation), soaria-controlsis an always-resolvable reference. (#3723) - Collapsible: link the trigger to its content region with
aria-controls, and give the content region a matchingid. Completes the disclosure pattern so assistive tech can move from the trigger button to the region it shows/hides (previously onlyaria-expandedwas set). (#3707) - Collapsible: the trigger button now shows a visible focus ring when focused via keyboard. The trigger's
all: unsetreset removed the browser's default outline without restoring a replacement, leaving keyboard focus invisible (WCAG 2.4.7). (#3722) - Keep Collapsible self-toggling when uncontrolled with onOpenChange (#3785)
useCollapsibletreated the presence ofonOpenChangeas a signal that the component was controlled: itstogglehandler fired the callback but skipped the internal state update, so an uncontrolled Collapsible given onlyonOpenChange(noisOpen) appeared stuck — the callback fired but the content never opened or closed. Control is now determined solely by whetherisOpenwas provided, mirroring howisOpenis derived. Uncontrolled usage drives internal state and firesonOpenChange; controlled usage still defers entirely to the parent. - SegmentedControlItem now forwards a consumer onClick, and add composeEventHandlers
A consumer
onClickonSegmentedControlItemwas silently dropped — the internal selection handler clobbered it. It now runs alongside selection (callpreventDefault()to opt out). The newcomposeEventHandlersutility chains handlers in order and stops when one prevents default, so components that own an interaction can also honor a consumer handler for the same event. - ContextMenu now anchors the menu to the right-click point relative to its context, so it follows the content on scroll and auto-flips at viewport edges instead of staying at a fixed screen position (#3465).
- DateTimeInput: the embedded time input now carries
aria-describedbyandaria-busylike the date input, so screen-reader users keep access to the field's description, status message, and disabled message when focused on the time half. (#3716) - DateTimeInput:
timeIncrementis now typed as a literal union of sensible increments (1 | 5 | 10 | 15 | 30) instead of an opennumber, so negatives, fractions, and absurd values are rejected at the type level rather than silently accepted. Adds an exportedDateTimeInputTimeIncrementtype (#2725) - focusableSelector: match only real links (
a[href],area[href]) instead of any element with an href attribute. Previously non-focusable elements carrying href could be treated as tab stops by useFocusTrap. (#3714) - useFocusTrap: focus now returns to the previously-focused element when a trap deactivates, so closing a Popover (Escape or light-dismiss) no longer drops keyboard focus to the page body. Components that already restore focus themselves are unaffected — the trap only restores when focus would otherwise be lost. (#3732)
- Forward consumer event handlers in SegmentedControl, CheckboxListItem, and SideNavCollapseButton
These components set their own
onClick/onKeyDown/onFocus/onBlurafter spreading{...rest}(or destructured the consumer's handler and never used it), so a consumer-supplied handler for the same event was silently dropped. They now compose the consumer's handler with the built-in one viacomposeEventHandlers, consumer-first — the consumer's runs and can callpreventDefault()to opt out of the built-in behavior. - Grid: with
columns={{minWidth, max}}, columns that are present now fill the row when fewer thanmaxfit. Previously themaxcap was applied to each track's max size, so a layout collapsing to a single column (e.g. on mobile) left dead space on the right instead of stretching to full width. The cap now limits the column count while letting present columns reach1fr. (#3391) - Icon: allow string (registry) icons to be made meaningful.
aria-hidden="true"is now applied before the prop spread, so consumers can override it (e.g.aria-hidden={false}+role="img"+aria-label) for a standalone informational icon. Previously registry-mode icons hardcodedaria-hiddenafter the spread, making it impossible to override — inconsistent with component-mode icons, which already allowed it. Default behavior (decorative, hidden) is unchanged. (#3710) - Layer/Popover: anchor-positioned popovers now mirror in RTL.
placement/alignmentstart/endare logical (inline-start/inline-end), so DropdownMenu, Selector, Typeahead, date inputs, and every other context-mode popover opens toward the correct side under RTL automatically via CSS. LTR behavior is unchanged (#3389). - Lightbox: navigating between images now announces the new image and its position (e.g. "Sunset over the bay, 3 of 12") to screen readers via a polite live region. Previously only the visual counter updated. (#3727)
- MobileNav forwards pass-through attributes and applies consumer className/style
MobileNav declared
BasePropsbut silently discardedclassName/style(destructured to unused vars) and dropped every other pass-through attribute (id,aria-*,data-*beyonddata-testid, event handlers). It now mergesclassName/styleand spreads the remaining props onto the<dialog>, and composes a consumeronClickwith the backdrop-dismiss handler viacomposeEventHandlers. - Forward unhandled pass-through attributes (
data-testid,aria-*,id, etc.) to the primary rendered element of Switch, Pagination, RadioListItem, SideNavSection, TableHeader/TableBody/TableFooter, and TopNavMegaMenuFeaturedCard. These components previously dropped attributes not explicitly consumed, so test hooks and accessibility attributes silently disappeared. - NumberInput with hasClear commits null when cleared from the keyboard (#3599) Deleting the text and blurring (or pressing Enter) silently reverted to the previous value — only the X button honored the clearable contract. An emptied input now commits onChange(null) on blur/Enter when hasClear is set; non-clearable inputs keep the revert behavior.
- paginateData clamps invalid page numbers instead of slicing from the end (#3593) A negative page fed a negative start index to Array.slice, which counts from the end of the data — page -1 returned the dataset's tail dressed up as a page — and fractional pages returned slices straddling two pages. page now gets the same coercion pageSize received in #3380.
- PowerSearch: changes to the visible result count are now announced to screen readers via a polite live region, mirroring Typeahead's wording. Previously the count only updated visually. (#3726)
- ProgressBar: treat a non-finite value/max as empty progress
A NaN
value(e.g. an upstreamloaded / total * 100with total 0) leaked the literal string "NaN" intoaria-valuenow, the value label, and the fill width style. Non-finitevalue/maxnow route through the same empty-progress handling asmax={0}. - ProgressBar: guard the value label against a zero max
When
maxwas0(or negative), the default value-label formatter producedNaN%(0/0) orInfinity%. That string was rendered visually and written intoaria-valuetext, so screen readers announced "NaN percent". Guard it the same way the fill percentage already is (max > 0 ? … : 0). - Resizable: keyboard resizing now works. The keydown handler was attached to a non-focusable child of the separator, so Arrow/Home/End keys never fired for keyboard users; it now lives on the focusable
role="separator"element per the WAI-ARIA window-splitter pattern. (#3729) - ResizeHandle: release window drag listeners when unmounted mid-drag A drag in flight when the handle unmounts never receives its pointerup, so the window pointermove/pointerup/pointercancel listeners leaked — every subsequent pointer move kept resizing the still-mounted region, and the body cursor/user-select overrides stuck. Unmount now tears down the in-flight drag's listeners and restores the body styles.
useTheme()/resolveThemeTokens()now resolve derived tokens that reference other tokens (e.g.--color-text-accent: var(--color-accent)) to concrete raw values, following reference chains iteratively. Supported CSS color functions (color-mix(in srgb, …)) are evaluated against those values, so canvas/SVG/data-viz consumers get usable colors instead ofvar(...)orcolor-mix(...)strings (#3697). Also adds shared color parsing/formatting primitives (parseHex,parseRgb,parseColor,formatHex,formatColor) under@astryxdesign/core/utils, unifying the color parsers previously duplicated across the theme layer.- SegmentedControl: tabbing through no longer rewrites the value (#3597) When value matched no enabled item (initial empty state, stale server value, or the selected item disabled), the roving tab stop fell back to the first enabled radio and selection-follows-focus fired onChange with it — a keyboard user mutated the form just by tabbing past the control. Selection now only follows focus moves within the group (arrow/Home/End); entering focus is a pure focus move, and click selection is unchanged.
- SegmentedControl and SegmentedControlItem forward data-testid to the DOM
Both components declared
BaseProps(sodata-testidand otherdata-*attributes type-check) but silently dropped them: neither captured...restnor spread the remaining props onto its rendered element, so the attribute never reached the DOM. They now capture...restand spread it onto the radiogroup<div>/ radio<button>(the same rest-spread fix applied toCheckboxInputin #3738), placed before the component's ownrole/aria-*so those can't be overridden. - SideNav: don't render the empty sticky-bottom container when
collapsible.hasButtonis false. Previously the footer container rendered whenever the sidebar was collapsible — even with the built-in button opted out and nofooter/footerIcons— leaving an empty, bordered container at the bottom of the nav. The container now renders only when it has visible content (a footer, footer icons, or the built-in collapse button). (#3603) - Markdown/useStreamingText: streaming text now respects
prefers-reduced-motion— the per-character reveal snaps to the full text and the entry fade is disabled for users who prefer reduced motion, matching the convention already used by Spinner, Skeleton, ProgressBar, and Chat. (#3730) - Table: always render a numeric aria-valuenow on the column resize handle. The focusable resize separator omitted aria-valuenow before its width was measured, which failed the axe aria-required-attr rule (a focusable role="separator" requires aria-valuenow); it now falls back to the column minWidth. (#3343)
- Table rows re-render when a field is removed from the row object (#3595) The row memo compared only the keys of the new item, so a field cleared by omission (optimistic update, server response) never invalidated the memo and the cell kept rendering the deleted value indefinitely. A key-count check now catches removed properties.
- Table selection: select-all no longer reads checked over an empty filtered table (#3591) With rows selected and a filter matching nothing, the union-based all-selected check treated the invisible selection as "all selected": the header checkbox rendered checked over an empty table, and deselect-all was a no-op because the hidden keys count as frozen. Zero actionable rows now reads as not-all-selected; the frozen-selection preservation itself is unchanged.
- Table sort: group NaN cells with null instead of corrupting the order (#3585) A NaN cell hit the numeric fast path in defaultCompare, and the NaN comparator result reads as "equal" to Array.sort — making the comparator inconsistent and silently mis-ordering the other, valid rows. NaN now sorts to the end alongside null/undefined.
- Table: column headers now render with
scope="col"so screen readers correctly associate data cells with their column headers. Consumer-provided scope via column header props still takes precedence. (#3715) - TabList: the overflow tab menu now uses a roving tabindex — one tab stop with arrow-key navigation between items — instead of making every overflow item a separate tab stop. (#3728)
- Document the full themeProps() selector surface and guard it against drift (#3741)
theming.targetsis the documented CSS surface of a component — the stableastryx-*classes it renders and the visual props it reflects as data attributes. It was hand-authored while the truth lived inthemeProps()calls in the source, and nothing kept the two in agreement, so it drifted twice (#3652, #3680) and was drifted again. - Thumbnail: give the labeled root a group role so its accessible name is valid. Previously the file name was set via aria-label on a plain div with no role, which axe flags as aria-prohibited-attr (serious) because a generic element cannot carry a name. (#3343)
- TimeInput: typed-invalid input (e.g. an out-of-range time that will be reverted on blur) now sets
aria-invalidand announces "Invalid time" via an assertive live region, matching DateInput, NumberInput, and DateTimeInput. Previously only the visual red border signalled the invalid state. (#3718) - Timestamp: render nothing instead of crashing on an unparseable value
An unparseable
value(a malformed date string, or a NaN timestamp from missing data) produced an Invalid Date whose formatting throws "Invalid time value", crashing the whole tree. Invalid values now render nothing and log a console warning instead. - Timestamp: keep relative time within its own tier
Relative-time tiers guarded the raw diff with
<but displayed the count withMath.round, so just under a boundary it rendered "60 minutes ago" / "24 hours ago" instead of "1 hour ago" / "1 day ago" (and the same in the future direction). Floor the per-tier count so it can never reach the next tier. - Toast fallback viewport resolves the app's theme mode instead of OS preference (#3743)
The fallback mounts via createRoot() on a disconnected tree, so Toast's useTheme() couldn't see ThemeContext and fell back to prefers-color-scheme — when that disagreed with
<Theme mode>, the toast's inverted-surface text/icon could compute to the same color as its own background. useToast's fallback container now mirrors<html data-theme>anddata-astryx-themedirectly (kept live via MutationObserver), and useTheme() itself falls back to reading<html data-theme>before assuming OS preference when no ThemeContext ancestor is reachable — the mechanism that actually resolves Toast's JS-computed mode for disconnected trees like this one. - Toast: onHide fires exactly once, and a paused auto-hide timer survives viewport re-renders (#3589) A second dismissal during the exit transition (double-click, auto-timer plus manual dismiss()) double-fired onHide; and because the timer effect depended on the viewport's per-render onDismiss identity, any other toast arriving or leaving silently restarted — and un-paused — every mounted toast's auto-hide timer. Exiting toasts are now tracked in a ref before onHide fires, and the timer reads onDismiss through a ref so it only restarts on a genuine duration change and respects the paused state.
- Typeahead/Tokenizer discard out-of-order async search results (#3587) Each search now claims a new generation, so a slow response for an abandoned query can no longer overwrite the results of the current one (previously the last response to resolve always won, and Enter could select an item from a query the user had already replaced).
Documentation
- Correct Carousel doc drift and translate its Chinese usage block (#3532) The Carousel docs described behaviors the component doesn't have: there is no scroll-driven scale effect on items, and the prev/next buttons are driven by per-edge overflow (each appears when the content can scroll in that direction), not by hover or platform. Descriptions now match the source. Also translates the docsZh usage block, which was still in English.
- DialogHeader: add property-editor defaults and example blocks (#2719) The DialogHeader docsite page rendered an empty preview because the properties editor had no default prop values, and it had no example blocks. Add playground defaults (title, subtitle, divider) so the preview is meaningful out of the box, plus example blocks covering a basic header, a header with a close button, and one with start/end content.
- Correct useInteractiveRole isDisabled docs for disabled href (#3786)
The
isDisabledJSDoc claimed a disabledhref"falls back to button". It does not: a disabledhrefis skipped at the link step and resolved by the remaining priority checks, so with noonClickand no interactive context it lands on'inert'— asTokenalready relies on for disabled links. TheisDisableddoc, the step-1 inline comment, and the priority summary now describe the actual behavior. Docs only; no runtime change. - Document when playground.overlay applies: components with no inline containment (MobileNav, Lightbox) use it, while Dialog, AlertDialog, and CommandPalette intentionally keep their contained isInline previews so knobs stay usable. Adds regression tests guarding both shapes (#3657)
- Lightbox Properties preview shows the overlay open trigger instead of an empty stage (playground.overlay)
- Document the full
themeProps()selector surface in component theming targets. A sweep of everythemeProps()call against thetheming.targetsentries found 19 gaps across 16 components where a visual prop or state had no documenteddata-*selector, so the CLI theming table hid part of the themeable surface: missing target entries (Citation, ToggleButton, Banner content, OverlayScrim, NavHeadingMenu, NavHeadingMenuItem) and missingvisualProps/stateson existing entries (Chat message density, Checkbox, Code color, CodeBlock container, DropdownMenu item size, SegmentedControl item, SelectableCard variant, SideNav item, Timestamp format, Tokenizer status, TopNav item selected, TreeList item density, Typeahead size).
Contributors
Thanks to everyone who contributed to this release:
0.1.4
New Features
- Code: add
colorandsizeprops.coloraccepts'primary' | 'secondary' | 'inherit'and now defaults to'primary'(mirroring Text's color subset); previously the color was left to inherit implicitly.size="inherit"makes inline code adopt the surrounding text'sfont-sizeandline-height. ExportsCodeColorandCodeSizetypes (#2846) - Markdown: support CommonMark link reference definitions. Reference-style "footer" links — full
[text][label], collapsed[text][], and shortcut[text](plus their![alt]image forms) — now resolve against a[label]: destination "title"block, which is stripped from the output instead of leaking as a visible paragraph. Labels match case-insensitively with collapsed whitespace; top-level definitions are collected across the document (so a reference can precede its definition, including in the streaming/incremental parser, whose settled-block cache invalidates when definitions change). Footnotes ([^1]) are intentionally left untouched. Known limit: a definition nested inside a blockquote/list resolves within that container but is not yet exposed document-wide. (#3621) - Native form participation for custom inputs via htmlName (#3343)
Switch, CheckboxInput, RadioList, Slider, Selector, MultiSelector, and Tokenizer now accept the same
htmlNameprop TextInput and NumberInput already had, so they serialize into native form submission. Components with a real native input (Switch, CheckboxInput, RadioList) forward the name; the synthetic controls render hidden inputs that mirror native semantics — one entry per value for MultiSelector/Tokenizer (like a multi-select), string value for Slider (two entries in range mode), and exclusion from FormData when disabled. - Add
useTableRowExpansion— expand/collapse tree rows inline.
Fixes
- Button: keep edge compensation working when a ghost button also has a tooltip. The tooltip is now attached via the tooltip hook instead of a wrapper element, so the button stays a direct child of its container — no extra DOM node, no layout shift, and containers (Toolbar, Banner) still detect the edge-compensation marker via their direct-child
:has()selector and pull the button flush to the optical edge. (#2578) - Calendar: stop range-highlighting adjacent-month (outside) days, and cap the range highlight where it meets a disabled or adjacent-month day. In the two-month range view the same date renders in both panes, so the spillover copy on the neighbouring month's pane was drawn as part of the selection; outside days now never receive selection, range, or preview state. A highlighted day next to a disabled or outside day now gets a rounded end cap so the run reads as properly terminated instead of running square-edged into the gap. (#2715)
- Code and CommandPaletteEmpty now forward props correctly (#3620)
Codespreads rest props (aria-*,role, event handlers) onto the DOM element.CommandPaletteEmptyapplies thexstyle/className/styleescape hatches and theme props. - DateRangeInput: use the label type-size token for the trigger field. The trigger was reading the body size/leading tokens (
--text-body-size/--text-body-leading) instead of the label ones (--text-label-size/--text-label-leading), so its text rendered a step larger than the other date inputs. (#3655) - Spinner: promote the canvas to its own compositor layer (
willChange: transform) so rotation stays smooth on WebKit — fixes wobbly spinning in Safari and Tauri WebViews. (#3628) - Text: apply the documented
sizeprop as a font-size override (#3615)Textnow reflectssizein theme props and applies the corresponding typography size token after its type-based baseline styles. The override changes font size while preserving the selected text type's line-height, weight, and family behavior.
Documentation
Other Changes
- Inherited-columns mode: child rows use the same columns as their parents, indented by depth. Injects a chevron column; clicking (or right-click → "Expand/Collapse row") toggles a row's children.
- Headless: the consumer owns
expandedKeysstate; the plugin provides the UI. Pair withuseTableRowExpansionStateto flatten a tree into the visible rows. - Optional expand-all header toggle via
isAllExpanded+onToggleExpandAll. - Optional
expandOnRowClickto toggle by clicking anywhere in the row. - Contributes a context-menu action for expand/collapse (via the
contextMenuActionssystem).
Contributors
Thanks to everyone who contributed to this release:
0.1.3
Breaking Changes
- DropdownMenu, ContextMenu, MoreMenu: removed the
hasAutoFocusprop. Menus now always focus their first item on open (the correct APG menu-button behavior). PreviouslyhasAutoFocus={false}left the menu keyboard-unreachable and undismissable — the prop existed only as an escape hatch for documentation previews, which no longer need it.
New Features
- Calendar:
weekStartsOnnow also accepts a three-letter day name ('sun'–'sat', case-insensitive) in addition to the numeric0–6, so the starting day is self-documenting at the call site (e.g.weekStartsOn="mon"). Numbers keep working unchanged. Adds an exportedDayOfWeekNametype and anormalizeDayOfWeekhelper (#2843) - CheckboxInput/Switch/Slider/RadioList/CheckboxList/SegmentedControl/Tokenizer/PowerSearch: disabledMessage prop shows a tooltip explaining the disabled state (#3509)
- DateInput can now be used inside InputGroup with shared addon styling and group label/description/status ARIA wiring (#3520).
- DateTimeInput: add a
timePlaceholderprop to customize the time-portion placeholder (previously hardcoded to "Select a time" with no override).placeholdercontinues to control the date portion; the focused typing hint (e.g. "e.g., 2:30 PM") is unchanged (#2729) - Toolbar, TabList, and SegmentedControl now show an ephemeral "← → to navigate" hint on first keyboard focus, teaching sighted users that arrow keys navigate within the group. Adds a showcase block and Storybook story for useKeyboardHint.
- Export
themeProps(and itsThemeProps/ClassProps/ClassValue/ThemeDataAttributestypes) from@astryxdesign/core/utils, so packages building on core can generate the stable astryx class +data-*attribute surface through the public API instead of reaching into core internals. - MultiSelector can now be used inside InputGroup as a decorated single-line control, sharing the group label, description, status, and connected border treatment (#3520).
- Typeahead, DateInput, DateRangeInput, DateTimeInput, and TimeInput:
disabledMessageprop shows a tooltip explaining the disabled state on hover and keyboard focus, keeping the control focusable viaaria-disabledwhile activation stays blocked (#3509) - Popover: expose hasLightDismiss and add hasEscapeDismiss so consumers can opt out of outside-click and Escape dismissal for explicit-dismiss surfaces like onboarding coachmarks. usePopover accepts the same new hasEscapeDismiss option; with it off, no handler is registered on the shared Escape stack so the key falls through untouched (#3287)
- Selector/MultiSelector: disabledMessage prop shows a tooltip explaining the disabled state (#3347)
- Selector can now be used inside InputGroup as a decorated single-line control, sharing the group label, description, status, and connected border treatment (#3520).
- Stack/HStack/VStack: add
padding,paddingInline,paddingBlock(spacing-scale inner padding) andisScrollable(overflow: auto) props; StackItem also gainsisScrollable. These match the existingpadding/isScrollableprops onCard,LayoutContent, andLayoutPanel, so common frame layouts no longer need inlinestyle={{}}for padding or the flex scroll-region pattern. - Standardize layout component sizing props. Add
maxWidth/minHeighttoStack,Grid, andCenter(matchingSection/Card), migrateLayout/LayoutHeader/LayoutFooter/LayoutPanelsizing to the sharedSizeValuetype, and drop redundantxstyle/className/stylere-declarations onStack,StackItem, andLayout. No runtime behavior change. - Add a plugin-contributed right-click context-menu system to
Table. Right-clicking a column header or a row shows a menu of actions aggregated from every enabled plugin (instead of the browser's generic menu). - TabList is now a single tab stop with arrow-key navigation between tabs (roving tabindex) — Arrow keys move focus, Home/End jump to the ends, disabled tabs are skipped, and focus wraps. This does not change the semantic roles (still
<nav>/aria-current); the full tablist/tab/tabpanel conversion is tracked separately in #3335. Reference (#3343). - TextInput/NumberInput/TextArea/FileInput: disabledMessage prop shows a tooltip explaining the disabled state (#3509)
- Add InputGroup compatibility for TimeInput (#3520)
- TreeList now implements the full WAI-ARIA APG Tree View keyboard pattern. Roving tabindex places a single tab stop on the treeitem rows (defaulting to the selected item or the first enabled row), and arrow keys move focus in visible order: ArrowDown/ArrowUp step between visible rows (skipping disabled), ArrowRight expands a collapsed parent then enters its first child, ArrowLeft collapses an expanded parent or moves to the parent row, and Home/End jump to the first/last visible row. Enter and Space activate the row's action (or toggle a parent without its own action), and typeahead moves focus to the next row whose label matches the typed characters. Each treeitem now also exposes
aria-level,aria-posinset, andaria-setsize. Builds on the interim keyboard-expandable toggle in (#3344). Part of the accessibility & keyboard-management program (#3343). - Add InputGroup support for Typeahead (#3520)
- Add
useAnnounce— an accessibility hook that speaks messages to screen readers through persistently-mounted, visually-hidden polite/assertive live regions. Because the regions are created once (not together with their content), announcements are reliable. Wired intoTypeahead/BaseTypeaheadto announce result counts and "no results found" during search, which were previously silent (#3343). - Add
useKeyboardHint— shows an ephemeral "← → to navigate" badge anchored to the focused item when a composite widget first receives keyboard focus. Teaches sighted keyboard users that arrow keys navigate within a roving-tabindex group. Renders in the top layer (popover="manual") with CSS anchor positioning so it is never clipped by overflow containers. Auto-dismisses on first arrow press, timeout, or blur; does not re-show for that instance.aria-hidden(visual-only; screen-reader users already hear the role). - Add
useTypeahead— a first-character (type-to-focus) search hook, and wire it intoDropdownMenu. Typing a letter jumps to the next menu item whose label starts with it; repeated presses of the same letter cycle through matches; the buffer resets after 750ms; disabled items are skipped. The hook is additive and collection-agnostic (composes withuseListFocus/useGridFocusviaonMatch), so menus/listboxes gain APG typeahead which astryx previously lacked (menus-11, infra-14) (#3343). useListFocusgains opt-in roving-tabindex ownership (hasRovingTabIndex), caret-aware arrow handling that leaves keys to nested text inputs and contenteditables (hasCaretGuard), RTL horizontal navigation (isRtl), ahasHomeEndtoggle, andorientation: 'both'for four-arrow navigation.Toolbarnow uses it — it is a single tab stop and no longer steals the caret from a toolbar text input or composer (#3343).- Add
VisuallyHidden— an accessibility primitive that renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls,aria-liveannouncement regions, and supplementary screen-reader context. Renders a<span>by default; useasfor block/live-region elements (#3338).
Fixes
- Announce file selection, page changes, and multi-select count via the live-region hook (#3343) FileInput now announces successful file selection, Pagination announces page changes, and MultiSelector announces selection-count changes, all through the shared visually-hidden polite live region so these previously-silent surfaces are audible to screen-reader users.
- Avatar: an avatar with no
nameoraltis now decorative (role="presentation"+aria-hidden) instead of being announced with the meaningless generic name "Avatar". When named, the inner<img>uses an emptyaltso the accessible name isn't announced twice (once by therole="img"wrapper, once by the image) (#3343). - Breadcrumbs: auto-detected current breadcrumb now places
aria-current="page"on the item's content element (link/button/span), matching the explicitisCurrentpath, instead of on the outer<li>. When the last breadcrumb is a link, the anchor itself now carriesaria-currentso screen readers announce it as the current page (#3343). - Breadcrumbs: BreadcrumbItem now forwards remaining BaseProps (id, aria-, role, event handlers, data-) to the underlying
<li>element. Previously these props were accepted by TypeScript but silently dropped at runtime. - ButtonGroup: remove the invalid
aria-orientationattribute from therole="group"element, which was flagged by axe (aria-allowed-attr). Orientation is still reflected viadata-orientationand drives keyboard navigation and styling, so behavior is unchanged. Also fixes Schedule, which reuses ButtonGroup internally. - Calendar: cross-month keyboard navigation now resolves the focused date from the machine-readable
data-dateattribute instead of parsing the localizedaria-labelwithnew Date(). Previously, month-boundary arrow keys and PageUp/PageDown silently stopped working in non-English locales (e.g. fr-FR, ja-JP) where the label was unparseable (#3343). - Calendar: the month view now uses a valid ARIA grid structure — the weekday names are
columnheadercells inside thegrid, each week is arowwhose direct children aregridcells, and week-number cells arerowheaders. Arrow-key navigation now lands on the correct dates when some days are disabled (viamin/max/dateConstraints): moving up/down keeps the true 7-column geometry and skips disabled days to the same weekday, instead of shifting to the wrong weekday. (#3343) - Carousel, Lightbox: keyboard focus is no longer trapped on invisible or unmounted edge controls. Carousel's scroll left/right buttons, when at an exhausted edge (or when there is no overflow), were hidden with
opacity: 0/pointer-events: nonebut stayed in the tab order, so keyboard users could focus invisible controls (WCAG 2.4.7); they are nowdisabledin that state (still mounted, removed from the tab order and a11y tree). Button-driven scrolling also now respectsprefers-reduced-motion(usesbehavior: 'auto'instead of hardcoded'smooth'). In Lightbox gallery mode, the Prev/Next buttons previously unmounted at the range ends, so advancing onto the first/last item removed the focused control and dropped focus to<body>, dead-ending keyboard navigation; they now stay mounted and becomedisabledat the boundaries so focus stays within the dialog and arrow-key navigation keeps working (#3343) - Chat composer: the message input now uses
role="combobox"when triggers (mentions, slash commands) are configured, and stays a plainrole="textbox"otherwise. Combobox attributes (aria-expanded,aria-haspopup,aria-controls,aria-activedescendant) are only valid on a combobox, so applying them to a textbox was flagged by axe (aria-allowed-attr). (#3343) - ChatMessageList: add an
isStreamingprop that marks therole="log"regionaria-busywhile an assistant message streams in. Previously the polite live region re-announced the accumulating partial text on every token; withisStreamingset for the duration of a stream, screen readers wait and announce the completed message once (#3343). - CheckboxInput: stop setting a redundant
aria-checked="mixed"on the native<input type="checkbox">for the indeterminate state. The nativeindeterminateDOM property (which browsers already map toaria-checked="mixed") is authoritative; the extra attribute could desync from or override the native state (#3343). - CheckboxList: the checkboxes are now wrapped in a
role="group"named by the field label viaaria-labelledby(and associated with the description/error), instead of a flat list with an orphaned labelhtmlFor. Screen-reader users now hear the group's name and context (#3343). - CheckboxListItem: drop the invalid
aria-checkedfrom the list row.aria-checkedis not allowed onrole="listitem"(axe: aria-allowed-attr); checked state is already conveyed by the row's inner checkbox. This also fixes Markdown task lists, which render task items through CheckboxListItem. (#3343) - Citation: linked number-variant badges keep their accent-muted background (previously rendered transparent), and the badge now uses the secondary text color (#3508)
- Citation: only apply
role="doc-noteref"on the linked (anchor) form. On a plain unlinked span the role is not permitted (axe: aria-allowed-role), so it is omitted there while thearia-labelstill names the citation. (#3343) - Selector/MultiSelector/Typeahead: the highlighted option is now scrolled into view during keyboard navigation, so arrow keys no longer move the highlight off-screen in long lists (matches CommandPalette) (#3343).
- CommandPalette: the empty state ("No results") no longer flashes when typing further characters into an already-empty search. The empty state stays mounted for the full duration of the pending search instead of briefly unmounting and re-appearing.
- ContextMenu: Escape now closes the menu even when it was opened without auto-focus (e.g. table row menus), via a document-level Escape listener instead of one that only fires when focus is inside the menu. Focus is also restored to the previously focused element on close, instead of falling to
<body>. Escape during IME composition is ignored (#3343). - ContextMenu: can now be opened on touch (long-press) and by keyboard. A long-press (500ms, cancelled by a 10px finger move) opens the menu at the touch point — previously context menus were unreachable on iOS Safari, which never fires
contextmenuon long-press. A keyboard-initiatedcontextmenu(Shift+F10 / the Menu key), whose coordinates are (0,0), now anchors the menu to the trigger's box instead of the viewport corner (#3343). - DateInput/DateTimeInput: the date field's calendar popover can now be opened from the keyboard with
ArrowDown/Alt+ArrowDown(APG combobox), not just by clicking. DateTimeInput's time input no longer uses a hardcoded Englisharia-label="Time"— it defaults to"{label} time"(tied to the field label and localizable) and accepts an explicittimeLabelprop (#3343). - DateRangeInput: the preset sidebar is now a labeled
role="group"of action buttons instead of arole="listbox"ofrole="option"buttons. The listbox/option roles announced a single-tab-stop listbox that contradicted the actual Tab-between-buttons interaction (no listbox keyboard model existed). The currently-applied preset is marked witharia-currentrather thanaria-selected(#3343). - docs.mjs: resolve the package directory with fileURLToPath so component docs work on Windows, where URL.pathname yields drive-letter paths like /D:/... that made --list silently print nothing and single-component lookup crash with ENOENT (#3331)
- DropdownMenu: pressing Tab in an open menu now closes it (APG menu-button pattern) and returns focus to the trigger, instead of leaking focus into the page while the menu stayed open (#3343).
- Escape now dismisses only the top-most open layer instead of closing every open layer at once — a popover or menu nested inside a Dialog no longer closes both on a single Escape press. Also guards against IME composition: pressing Escape to cancel a CJK/IME composition inside a Dialog or popover no longer closes the overlay (#3343).
- Vertically center the optional/required indicator in
FieldLabel. ThelabelandoptionalRequiredstyles never set an explicitlineHeight, so both fell back toline-height: normal(~1.2), producing mismatched line boxes (~16.8px for the 14px label vs ~14.4px for the 12px "∙ Required" text). WithalignItems: centerthe smaller indicator centered within its shorter box and rendered visually high relative to the label. - FileInput:
aria-describedby,aria-required, andaria-invalidnow sit on the focusablerole="button"control instead of the visually-hiddentabIndex={-1}file input that never receives focus. Screen-reader users now hear the field's help text, required state, and error state. The hidden native input is also markedaria-hiddensince it is not focusable (#3343). - useFocusTrap: the focusable-element detection now includes
contenteditable, media withcontrols,iframe, and an open<details>'s<summary>, and excludes elements hidden viadisplay:none/visibility:hiddenor insideinert/hiddensubtrees. Previously a trapped surface whose only interactive content was (e.g.) a contenteditable composer could let Tab escape (infra-8). - Grid no longer writes
grid-template-columns/grid-auto-rowsas raw inline styles. Track templates now use StyleX dynamic styles (CSS-variable indirection), so consumerxstyleoverrides — including responsive@mediaoverrides — take effect instead of being defeated by inline styles. - NumberInput, DateInput, and DateTimeInput now set
aria-invalid="true"and announce a short message (e.g. "Invalid number" / "Invalid date" / "Invalid time") via a visually-hiddenrole="alert"live region while the currently typed input is unparseable, instead of only dimming the text color and then silently reverting the value on blur. Screen-reader users now get feedback that their entry was rejected rather than silence, and the invalid state is no longer signaled by color alone (WCAG 3.3.1 Error Identification, 1.4.1 Use of Color). The revert-on-blur behavior is unchanged. (#3343) - InputGroup: grouped TextInput and NumberInput controls now include both the group label and their own label in the input name, while preserving the group's description and status associations (#3343).
- InputGroup: the group is now named by the field label via
aria-labelledbyinstead of a duplicatedaria-label, and the label no longer carries an orphanedhtmlFor(itsinputIdwas never handed to a child). Uses theFieldisGroupLabel/labelIDsupport (#3343). - Kbd: the component is no longer entirely
aria-hidden. It now exposes a spoken accessible name (e.g. "Command + K") built from screen-reader-friendly key labels, while the visual glyphs (⌘, ⇧, ↵, …) are hidden from assistive tech. Previously any shortcut communicated only viaKbd— including CommandPalette's footer hints — was invisible to screen-reader users (#3343). - Use Kbd for arrow-key navigation hints and space the hint farther from focused controls so outlines stay visible.
- Layer/popover entry animations now honor
prefers-reduced-motion. The shared layer slide/scale keyframes (used by DropdownMenu, Popover, HoverCard, Tooltip, Selector, and other popover surfaces) and theuseEntryAnimationpresets disable their keyframe animation underprefers-reduced-motion: reduce, so layers appear instantly instead of translating/scaling in (#3343). - useLayer: the popover
toggleevent listener is now removed when the layer element detaches or when the handler identity changes (a newonHide), instead of accumulating stale-closure listeners on the same element. This prevents duplicate/staleonHidefiring over a layer's lifetime (#3343). - Link: hovering now shifts the link color via the hover tint (
color-mixwith--color-tint-hover, matching Slider/Switch/RadioList). This gives always-underlined links (hasUnderline) a visible hover affordance they previously lacked — their underline never changed on hover — without altering the default link's underline-on-hover behavior (#2852) - Link: external links (
isExternalLink) now include visually-hidden "(opens in new tab)" text so screen-reader and cognitive-load users are told about the new-tab context change — previously only a decorativearia-hiddenicon signalled it. The text is overridable via the newnewTabLabelprop for localization (#3343). - DropdownMenu/ContextMenu: the
role="menu"container now has an accessible name — DropdownMenu names it from the trigger's label, and ContextMenu exposes amenuLabelprop (default "Context menu"). ContextMenu also no longer placesaria-haspopup="menu"on its role-less, non-focusable trigger wrapper, where it conveyed nothing useful to assistive tech (menus-13, menus-15). - NavHeadingMenu:
onClick-only items (rendered without anhref) now activate on Enter and Space. Previously theserole="menuitem"elements had no keyboard activation, so keyboard and screen-reader users could focus them but not trigger them (#3333) - Pagination: coerce pageSize to a positive integer so 0/NaN/negative values no longer crash the dots variant (RangeError: Invalid array length) or render Infinity/NaN page counts; the Table pagination plugin applies the same guard since it computes totalPages independently (#3372)
- usePopover: add a
role('dialog' | 'none') andisModaloption so listbox and menu popups no longer announce a false modal dialog. Selector, MultiSelector, BaseTypeahead, PowerSearch, DropdownMenu, TabMenu, and the Chat mention menu now expose their ownlistbox/menurole instead of being wrapped inrole="dialog" aria-modal="true"while focus stays on the trigger. Genuine dialog popovers are unchanged (#3343). - ProgressBar: determinate progress now uses
role="progressbar"instead ofrole="meter".meteris for static gauges (disk usage, battery) that screen readers do not treat as live-updating task indicators; a progress bar conveys task completion and should be announced on update. Indeterminate progress was alreadyprogressbar(#3343). - RadioList: give an unselected radio group a deterministic keyboard tab stop. When focus enters a group with no selected value, the group now normalizes the entry point — first radio when tabbing forward, last radio when tabbing backward — matching the ARIA radio-group pattern. A selected value keeps its native tab stop, and moving between radios inside the group is never redirected. (#3390)
- RadioList: the group is now named via
aria-labelledbypointing at the field label element, and the label no longer carries an orphanedhtmlFor(it pointed at an id no radio used, so clicking it did nothing and the group was double-labeled).Field/FieldLabelgain optionallabelIDandisGroupLabelprops to support grouping controls (#3343). - Table, CodeBlock, and Markdown: the keyboard-focusable scroll containers now use
role="group"instead ofrole="region".regionis a landmark, so multiple same-named scroll regions on one page (e.g. several tables labelled "Table") triggered axelandmark-unique.groupkeeps the label and keyboard focusability without creating duplicate landmarks. (#3343) - CodeBlock/Table/Markdown: overflowing scroll regions are now keyboard-focusable (
tabIndex,role="region") so keyboard users can scroll long code and wide tables. CodeBlock's Copy button no longer collapses the block when clicked, and is no longer nested inside the collapsible header'srole="button"(#3343). - SegmentedControl: a disabled segment (including when the whole control is disabled) is no longer a keyboard tab stop. Previously the selected segment kept
tabIndex={0}while disabled, so it was focusable but silently dead — arrow keys and activation did nothing (#3343). - SegmentedControl: keep the radiogroup reachable by Tab even when the current
valuematches no item (or the selected item is disabled). Previously a stale/unmatched value left every segment attabIndex={-1}, so the whole control dropped out of the tab order. The first enabled segment is now promoted to the tab stop (#3343). - Selector/MultiSelector:
DeleteandBackspacenow clear the value from the focused trigger whenhasClearis set, so clearing a selection is no longer mouse-only. The clear button was already keyboard-reachable; this adds the keyboard shortcut path (#3343). - Selector/MultiSelector (
hasSearch): the popup's search input is now the combobox — it carriesrole="combobox",aria-expanded,aria-autocomplete="list",aria-controls, andaria-activedescendant, so screen readers announce the highlighted option as ArrowUp/Down move it. Previously the search input was a baresearchboxwhilearia-activedescendantstayed on the (now-unfocused) trigger, leaving highlight changes silent. InhasSearchmode the trigger is a plain button that opens the listbox rather than a second combobox (#3343). - Selector, MultiSelector: the combobox trigger is now keyboard-focusable (
tabIndex=0when enabled). Previously it wastabIndex=-1, so keyboard and screen-reader users could not open or operate the control in the default (non-search) mode. The Clear button is now keyboard-reachable too (#3320) - useLayer: guard
showPopover()/hidePopover()behind a feature check so overlays degrade gracefully instead of throwing a TypeError on browsers without the Popover API (Safari <17, Firefox <125) (#3343). - SideNavItem: for split-action items (a collapsible item with its own link/action),
aria-current="page"now sits on the focusable link instead of the non-interactive wrapper<div>, so screen readers announce the current page on the actual navigation element (#3343). - SideNavHeading: label the product icon link with the heading text so it has an accessible name. When superheadingHref, headingHref, and a menu were all set, the icon link to the heading href rendered with no text or aria-label, so axe flagged it under link-name and screen readers announced an unlabeled link. (#3343)
- Skeleton: the loading placeholder is now
aria-hiddenby default (it's decorative — the surrounding region conveys the loading/busy state) and its pulse animation is disabled underprefers-reduced-motion: reduce. Thearia-hiddendefault can be overridden by consumers (#3343). - Spinner: the rotation animation now slows substantially under
prefers-reduced-motion: reduce(matching ProgressBar) instead of spinning unconditionally. Therole="status""Loading" announcement still conveys busy state (#3343). - Table: proportional() and pixel() no longer throw when called from a React Server Component. The Table barrel carried a 'use client' directive that marked the pure column utilities as client functions; the directive now lives only on the component modules, and Table.doc.mjs documents which parts of the data-driven API are server-safe (#3457)
- TabList: stop rendering aria-orientation on the nav element. aria-orientation is not an allowed attribute on the navigation role, so it triggered a critical axe aria-allowed-attr violation (also surfaced via Toolbar and ToolbarEdgeCompensation stories that reuse the same DOM). The orientation prop still drives arrow-key navigation and the keyboard hint. (#3343)
- TimeInput/DateTimeInput: parse dotted meridiems correctly. "2:30 p.m." was silently accepted as 02:30 and "12 a.m." as noon because the meridiem-detection regex did not allow the dots that the AM/PM regexes accept; hasMeridiem is now derived from those regexes so they cannot drift (#3462)
- Toast: keyboard users can now reach and manage notifications. Pressing
F6jumps focus into the toast viewport (the newest toast's first control, or the container). Dismissing a toast that holds focus now hands focus to a remaining toast — or restores the element focused before entering the viewport — instead of dropping to<body>. Auto-hide timers also pause while the window is blurred and resume on focus, so a toast no longer silently expires while you're in another window or tab (#3343) - Toast: remove the invalid
aria-modalattribute from the notifications viewport.aria-modalis only valid onrole="dialog"/alertdialog, so declaring it on therole="region"viewport was flagged by axe (aria-allowed-attr). Because the viewport renders on every page, this surfaced the violation across the whole app (#3343). - Tooltip: satisfy WCAG 1.4.13 (Content on Hover or Focus). Tooltips can now be dismissed with
Escapewhile visible, and stay open when the pointer moves from the trigger onto the tooltip surface (a short hover bridge).useLayercontext render props gainonMouseEnter/onMouseLeaveon the layer container to support hoverable overlays. - TopNavHeading: give the logo an accessible name when it links to a destination. The logo image is decorative, so a logo wrapped in
headingHrefproduced an unnamed link (axe: link-name). It is now labelled fromheading(or a new optionallogoLabelprop for logo-only headings). (#3343) - TreeList: parent rows can now be expanded and collapsed from the keyboard. Any item with children renders a real focusable toggle button with
aria-expanded, so expansion no longer requires a mouse — previously items without anonClick/hrefhad no focusable control at all (#3343). - Typeahead/Tokenizer: close the results dropdown when focus leaves the input (e.g. tabbing away), matching the existing outside-click and Escape dismissal. Previously the menu could stay open after the trigger lost focus.
- ContextMenu and NavMenu heading menus now support first-character typeahead (type a letter to jump to the matching item), via the shared
useTypeaheadhook — matching DropdownMenu. MoreMenu inherits it through DropdownMenu (#3343). - useListFocus (menu/toolbar keyboard navigation): arrow keys, Home, and End now skip disabled items instead of stalling on one whose
.focus()silently no-ops. This unfreezes keyboard navigation in NavHeadingMenu and Toolbar/ButtonGroup when a disabled control is present. The default item selector also now matchesmenuitemradio/menuitemcheckbox(#3343).
Documentation
- Document Carousel's hasEdgeFade and padding props, supported by the component but missing from the props table, docsZh, and docsDense (same omission previously fixed for Text's justify and ToggleButton's isIconOnly). Also correct the Fade edges anatomy row to optional, since the mask is suppressible via hasEdgeFade (#3332)
- Fix stale references in the core README: rename the "XDS CLI" section to "Astryx CLI", correct component names to their current bare exports (Layout, AppShell, TopNav, SideNav), and update remaining XDS brand mentions to Astryx.
- Link: document
type="inherit"for inline links. The value was already supported (forwarded toText, which rendersfont-size/line-height: inherit), but undocumented — clarified thetypeprop JSDoc, added an inline-link example, and added regression tests covering the inherit/default-body behavior (#2927) - MetadataListItem: its docs page preview now renders inside a MetadataList wrapper with realistic defaults (#3318)
Other Changes
- Consolidated 5 inline visually-hidden style blocks into the shared VisuallyHidden primitive (Button, Link, ProgressBar, Switch, TextArea); no behavior change.
- Rename the Field
labelElementIDprop tolabelID, matching the(part)IDnaming convention used by the sibling props (inputID,descriptionID,messageID). The disambiguation between "the id applied to the label element" andinputID("the control the label points at") now lives in the prop JSDoc rather than the name. Also renamed on FieldLabel and updated the RadioList/CheckboxList/InputGroup consumers. No behavior change. (#3343) useGridFocusgainshasRovingTabIndex,handleFocus, andisRtl, matching theuseListFocusAPI. Calendar now usesuseGridFocusto own its roving tab stop, removing the unpublisheduseCalendarRovingTabindexhook.- SegmentedControl now uses the shared useListFocus roving-tabindex primitive instead of its inline keyboard handler and tab-stop repair effect; no behavior change. The component's ~60-line inline ArrowLeft/Right/Home/End handler and useIsomorphicLayoutEffect tab-stop repair are replaced by useListFocus({hasRovingTabIndex: true, wrap: true, orientation: 'horizontal'}), which owns the single roving tab stop, skips disabled radios, wraps, handles Home/End, and repairs the stop on mount/disable. Selection-follows-focus (APG radiogroup) is preserved via a container onFocus handler that selects the focused radio's value.
- Move
@stylexjs/stylexfromdependenciesto a requiredpeerDependency(^0.18.3). A consumer who authors their own StyleX now shares a single runtime with astryx — resolution dedupes to their own install in both browser and Node — instead of silently getting a second copy on version drift. An incompatible StyleX version is now flagged at install (npm errors, pnpm/yarn warn) instead of resolving silently. Consumers who don't author StyleX are unaffected: the runtime is still required to render astryx components and is auto-installed by npm 7+ and pnpm. - New
TableContextActiontype and an optionalcontextMenuActionsfield onHeaderCellRenderProps/BodyCellRenderProps. Plugins append their actions inside the existingtransformHeaderCell/transformBodyCelltransforms; the table concatenates them across plugins (never overridden), the same waystylesare merged. - The cell components (
TableHeaderCell/TableCell) own the menu wrapper and render it around their own content via theContextMenuActionsprop, so the cell controls how the wrapper interacts with padding / content sizing — and row menus work without invalid<tr>nesting. Actions group with dividers and show a checkmark for the active item; when none are contributed, the native browser menu passes through. contextMenuActionsaccepts either an array or a getter (() => TableContextAction[]); the getter is resolved lazily when the menu opens, so plugins with state-derived actions don't build arrays on every render.useTableSortableuses a getter so its checked/clear state always reflects the latest sort.- First contributor:
useTableSortableadds "Sort ascending / Sort descending / Clear sort" on sortable headers. - TabList now uses
useListFocus's built-in roving-tabindex support (hasRovingTabIndex) instead of a hand-rolled tab-stop repair effect. The hook owns the single tab stop — stamping tabindex 0/-1, repairing it on mount and as stops mount/unmount or toggle disabled, and keeping it in sync after clicks/programmatic focus viahandleFocuson the nav. Individual Tabs still rendertabIndex={isSelected ? 0 : -1}as the initial source of truth, which the hook's repair preserves. No behavior change. - useTreeFocus gains
hasRovingTabIndex+handleFocusfor internal tab-stop management; TreeList drops its inlineactiveIdstate and lets the hook own the roving tab stop (#3488).
Contributors
Thanks to everyone who contributed to this release:
0.1.2
Breaking Changes
Text,Heading,Link, andTimestamprename thecolor="active"value tocolor="accent", now mapping to the dedicated--color-text-accenttoken (legible accent text ink) instead of--color-accent. Runastryx upgradeto migrate call sites automatically. (#2863)
New Features
- Button: add
isInterruptibleto keep the button clickable while aclickActionis pending — the spinner andaria-busystill show, but the button is not disabled or deduped, so a re-click interrupts the in-flight action. ToggleButton's async toggle now runs through this path, staying interruptible. - Add a prebuilt UMD bundle (
dist/astryx.umd.js, globalAstryx) plusunpkg/jsdelivrfields, so the library works directly from a CDN via a<script>tag with no bundler. React/ReactDOM stay as peer globals; the StyleX runtime is bundled in. - Add
useTableStickyColumns— pin a contiguous run ofTablecolumns to the start and/or end edge with cumulative offsets and scroll-aware drop shadows. Configure with{ startKeys, endKeys }; an empty config is a valid no-op.
Fixes
- AvatarGroupOverflow now forwards rest props (data-, aria-, event handlers, id, role, tabIndex) to the rendered element, matching the behavior of Avatar and AvatarGroup.
- Fix HoverCard SSR hydration mismatch when used inside an SSR Client Component (#3107). The floating layer now renders inline instead of portaling to
document.body, so server and client markup match. No API change. - Kbd: use the
--color-border-emphasizedtoken for its bottom border instead of--color-border(#2850) - useLayer now treats
anchor-nameas a comma-separated list, so multiple layers can anchor to the same element (e.g. two TopNavMegaMenus in one nav) without clobbering each other's anchor. Previously the second menu lost its anchor and rendered over the nav. - Fix mobile nav drawer not re-opening after it is closed (#3091)
The AppShell mobile drawer mounts
MobileNavinside an<Activity>that switches tomode="hidden"when the drawer closes. On close, React runs the drawer effect's cleanup (with a staleisOpen) instead of re-running the effect withisOpen=false, so the deferreddialog.close()never fired and the native<dialog>was leftopenin the hidden subtree. The next open then skippedshowModal()(the dialog was already open), so the drawer could be opened and closed once but never re-opened. The effect cleanup now closes the dialog if it is still open, keeping the native dialog state in sync so a subsequent open cleanly callsshowModal()again. - Core components (
Banner,EmptyState,Markdown) no longer render a<p>by default — they render<div>(appearance unchanged). This avoids hydration mismatches when block content lands in a<p>.Markdownparagraphs userole="paragraph"; passcomponents={{paragraph: 'p'}}to opt back into<p>. Pagination'schangeActionis now interruptible — page changes run in a transition with optimistic page state, so rapid prev/next clicks advance through pages instead of being dropped.Button'sclickActionkeeps its single-fire guard.- make the
Sliderdefault track color visible on muted backgrounds The background track painted with--color-background-muted— the same token used for muted surface fills — so the track disappeared on muted backgrounds. The track now uses the dedicated--color-trackchannel token, which is designed to stay legible against body/muted surfaces. - Polish
useTableStickyColumnspinned-cell backgrounds so they match the rest of the row: - Table: the header row no longer picks up the
hasHoverrow highlight — hover (and striped) styling now applies to body rows only. Adds an internalisHeaderRowflag on the row component so the header row in<thead>opts out (#2734) Timestampnow renders the current time (and small clock skew up to ~30s in the future) as "now" instead of "in a few seconds" (#3099).- ToggleButton onPressedChange receives the click event for preventDefault opt-out
onPressedChangenow receives the originating click event as a second argument. Callingevent.preventDefault()skipspressedChangeAction, so a consumer can handle the toggle entirely inonPressedChangewithout firing the action — matching howSwitch'sonChangeandButton'sonClickalready gate their action props. Existing(isPressed) => voidhandlers keep working; the event is an added trailing argument. - Tokenizer/PowerSearch: align end content (clear button, resultCount) with the field's inline padding instead of hugging the border (~3px). It now uses spacing-2 (8px) to match the text/start-icon inset (#2849)
- Tooltip and HoverCard: add ARIA roles to the floating layers —
role="tooltip"on Tooltip (completing the ARIA tooltip pattern; the trigger already links viaaria-describedby) androle="dialog"on HoverCard. Plumbed via a new optionalroleon the layer render props. (#3240; Popover already exposesrole="dialog".)
Documentation
- Document Banner's
defaultIsExpandedprop, which controls whether the collapsible content area starts expanded but was missing from the docsite properties tab - Rename the ClickableCard and SelectableCard examples to follow the "Component — Variant" title convention (
Clickable Card — Nested Button,Selectable Card — Multi-select), and add playground defaults to both card docs so their docsite previews show realistic card content (#2877) - Declare playground scaffolds for the Chat sub-components so they preview at a realistic width (ChatComposer and ChatComposerDrawer wrap in a sized container, and the drawer seeds default content), and drop the redundant visible value label from the ChatComposerDrawer "With Progress" example while keeping the accessible label (#2877)
- Document two public props missing from the docsite properties tab: List's
start(ordered-list counter start) and CheckboxInput'sisReadOnly - Restore the Icon and Skeleton properties-tab previews on the docsite. Icon now seeds a default
icon(it was a required, non-generatable prop), and Skeleton renders with concrete preview dimensions instead of collapsing at100%(#2848, #2875) - Document Heading's
justifyprop, which was supported by the component but missing from the docsite properties tab (#2847) - OverflowList: seed example items via playground defaults so the docsite properties-tab preview renders a real list instead of an empty container (#2872)
- Document Section's
paddingBlockprop (block-axis padding override), which was supported by the component but missing from the docsite properties tab - Give the
Skeletonproperties-tab example explicit dimensions so it is visible TheSkeletondoc had noplaygroundconfig, so the interactive properties-tab preview fell back to the prop defaults ofwidth: '100%'/height: '100%'. With no sized parent, the skeleton collapsed to a zero-size (invisible) element. The doc now sets aplayground.defaultsofwidth: 320/height: 80so the shimmer placeholder renders visibly. - Update stale
facebookexperimental/xdsdoc/JSDoc links to the then-currentfacebook/astryxnamespace in source comments (theme/syntax@seereferences). The old org 301-redirects, so these weren't broken — just stale — and this matches the canonical org used elsewhere - Document Table's
verticalAlignandtextOverflowprops, which were supported by the component but missing from the docsite properties tab - Document TabList's
layoutprop ('hug' | 'fill') for tab sizing, which was supported by the component but missing from the docsite properties tab - Document Text's
justifyprop, which was supported by the component but missing from the docsite properties tab (same omission previously fixed for Heading) (#2847-adjacent) - Restore the Timestamp properties-tab preview on the docsite.
valueis a required prop with no semantic default, so the preview rendered "Invalid time value"; it now seeds a valid ISO 8601 date (#2877) - Document ToggleButton's
isIconOnlyprop, which was a supported public prop but missing from the docsite properties tab - Make the Toolbar "Table Filter" example use real Selector controls for its Status and Priority filters instead of buttons styled to look like dropdowns, and add meaningful playground defaults plus richer slot options (buttons, icon buttons, tabs, segmented controls, selectors) to the Toolbar docs (#2877).
Other Changes
- Pinned cells paint an opaque base via the overridable
--table-sticky-backgroundvariable (defaults to--color-background-card), fixing a grey mismatch in themes/modes wheresurface !== card(e.g. neutral dark). Consumers on a different backdrop override the variable. - The row's overlay (striping and/or hover) is replayed on the pinned cell via
a background-image gradient.
TableRowpublishes its current overlay color as the inheritable--table-row-overlayvariable, so pinned columns mirror the row exactly — striped when the table is striped, hover when enabled, nothing otherwise (no phantom stripes) — transitioning in lockstep with the row. background-clip: padding-boxkeeps the row divider visible on pinned cells.- New
transformScrollWrapperhook (+ScrollWrapperRenderProps) lets plugins attach arefto the horizontal scroll container and inject before/after chrome. transformHeaderCell/transformBodyCellnow receivecolumnIndexand the full orderedcolumnslist (also surfaced on the render props), enabling position-aware plugins such as sticky columns. Existing plugins are unaffected — the new args and methods are additive and optional.
Contributors
Thanks to everyone who contributed to this release:
0.1.1
Breaking Changes
- Rename
xdsTokenDefaultsexport totokenDefaultsThe token-defaults constant is renamed fromxdsTokenDefaultstotokenDefaults(exported from@astryxdesign/core/theme). Update imports accordingly. Part of removing xds naming from the public API.
Fixes
- Increase trailing padding on
ChatLayoutScrollButtonwhen a label is shown With a label (e.g. "New messages"), the chevron icon sits on the leading edge and the text on the trailing edge. The symmetric inline padding left the label text cramped against the pill's rounded corner. The trailing inline padding is now widened when a label is present, giving the text comfortable breathing room from the rounded edge. The icon-only (collapsed) state is unchanged and stays balanced. - Prevent
DateInputfrom crashing the page while typing an incomplete date. Typing a leading0or1(e.g. starting to enter01for January) could coerce the in-progress value into an invalid date with a year of0, which then threw aRangeErrorand crashed the surrounding page. Partial, not-yet-complete input is now treated as incomplete instead of being parsed into a date, so the field stays usable as you type. - Remove doubled focus ring on
Selector. The inner combobox button drew its own:focus-visibleoutline on top of the wrapper's:focus-withinring, producing a stacked, rounded outline over the trigger after selecting an option or navigating with the keyboard. The button now defers to the wrapper's focus ring, matchingTextInputandNumberInput. <Layout>…</Layout>no longer renders a blank page.Layoutis slot-driven (content/header/start/end/footer), and the natural nested form<Layout><LayoutContent /></Layout>previously type-checked and built green while dropping its children at runtime — an empty shell. Children now render as a shorthand for thecontentslot (<Layout>{main}</Layout>is equivalent to<Layout content={main} />), matching howCardandSectionaccept content; an explicitcontentprop still wins when both are provided.- ToggleButton runs pressedChangeAction in an interruptible transition with optimistic state
pressedChangeActionwas fired as a non-awaited promise, so the documented loading spinner never appeared and the toggle ignored the action's lifecycle. It now runs inside a transition with an optimistic pressed state, matchingSwitch:
Other Changes
- The optimistic pressed state flips immediately on click; the spinner is debounced so a fast action shows the new state without a spinner flash.
- The action is interruptible — clicking again while it is pending starts a new transition with the next optimistic state (e.g. true -> false -> true), instead of being dropped or guarded out.
- Synchronous handlers are supported too: a
pressedChangeAction(oronPressedChange) that synchronously triggers a suspending update, such as a router navigation that suspends on data, also drives the pending state.pressedChangeActionnow acceptsvoid | Promise<void>.
Contributors
Thanks to everyone who contributed to this release: