What's New
Release notes and changelog for all packages.0.2.0
Breaking Changes
- TabList: remove orientation prop (misleading no-op). The prop did not render vertical tabs; it only toggled the keyboard-hint badge arrows. Arrow navigation has always accepted both axes (horizontal and vertical) via orientation: both in useListFocus. Run astryx upgrade to auto-strip the prop from your code.
New Features
Avatargains optional interactivity viahref/onClick(withas/target/rel), following Button's element-swap trichotomy:hrefrenders a link throughuseLinkComponent,onClick(no href) renders a<button type="button">, and with neither the avatar stays the static, non-focusable element it is today (non-breaking default). Interactive avatars get the focus-visible accent ring and a required accessible name (fromalt/name). InsideAvatarGroup, interactive avatars — and an interactiveAvatarGroupOverflow— now share a single Tab stop with roving ArrowLeft/ArrowRight focus, and the group exposes a screen-reader keyboard hint viaaria-describedby. A purely static facepile is unchanged. (#4170)- Citation:
CitationSource.iconnow accepts aReactNode(e.g. an Astryx<Icon>, an SVG, or a custom element) in addition to an image URL string, and a newCitationSource.srcfield holds a favicon/logo image URL (mirroringAvatar/Thumbnail). Additive and non-breaking: a stringiconstill renders as the favicon<img>, so existing callers are unaffected. When both a nodeiconandsrcare set, the node wins. The icon stays decorative — the accessible name still comes solely from the citation'saria-label. - CodeBlock: move the collapse chevron to the left of the title/language label, following the leading-disclosure convention (points right
>when collapsed, downvwhen expanded). It grows into place (width + inline margin) so it slides the title over smoothly instead of popping in and shifting the header. Respectsprefers-reduced-motion(#4513) - Collapsible: expose the trigger button as a distinct theming target (
astryx-collapsible-trigger) so themes can style the trigger independently from the content — e.g. a heading font on the trigger while the content keeps the body font. - DateInput: add
astryx-date-input-clear-iconandastryx-date-input-toggle-icontheme targets on the clear and calendar-toggle glyphs, so consumers can recolor, resize, and hover-style each icon — and style the toggle's open/closed state — viadefineThemeinstead of a fragile descendant selector or raw CSS. The toggle reflects its open/closed state as adata-stateattribute.Iconnow fully handles its styling props (className,style,xstyle) so they compose with its base styles instead of being dropped. Default rendering is unchanged. - DateRangeInput: add
astryx-date-range-input-clear-iconandastryx-date-range-input-toggle-icontheme targets on the clear and calendar-toggle glyphs, so consumers can recolor, hover-morph, and resize them viadefineThemeinstead of a fragile descendant selector or raw CSS. The toggle icon reflects its open/closed state as adata-stateattribute.Iconnow fully handles its styling props (className,style,xstyle) so they compose with its base styles instead of being dropped. Default rendering is unchanged. - DateTimeInput: add
astryx-date-time-input-date-segmentandastryx-date-time-input-time-segmenttheme targets on the two segment wrappers, so a theme can restyle their geometry (padding/height/font) viadefineThemeinstead of being unable to reach them at all. Both reflectsizeandstatusas data attributes, mirroring the root target. Default rendering is unchanged. - DropdownMenu: add submenus via a single
DropdownMenuSubMenucomponent (or a nesteditemsarray in data mode). The row adopts DropdownMenuItem semantics (label / icon / description / isDisabled) and its children — or anitemsarray — become the flyout content. Flyouts open inline-end with auto-flip, hover-intent, and full keyboard support (Right/Enter/Space opens and focuses the first item; Left/Escape closes and returns focus to the trigger). - Bordered inputs gain a
statusVariant="tooltip"option that hides the status message box and surfaces the status as an info-tip on the on-field status icon. The icon is a real focusable button so the status is reachable by everyone: keyboard users tab to it (with a visible focus ring) and see the message on focus, pointer users see it on hover, and touch users tap to toggle it. The message is piped into both the input's and the button'saria-describedby, and the tooltip is dismissible with Escape. Added to TextInput, TextArea, NumberInput, DateInput, DateRangeInput, TimeInput, and FileInput. - The bordered input family now accepts a
statusVariantprop ('attached' | 'detached', default'attached') that forwards to the underlyingField, letting you float the status message below the input with spacing instead of overlapping it. Added to TextInput, TextArea, NumberInput, DateInput, DateRangeInput, TimeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput, and PowerSearch. Non-breaking: the default matches today's behavior. (#4187) - Add RTL direction API:
useDirection()hook,getLocaleDirection(locale)server-safe helper, and an optionaldirprop onInternationalizationProvider. - RTL: mirror directional disclosure/navigation chevrons under RTL via a shared
rtlStyles.mirrorCSS transform, applied to the icon wrapper in Lightbox and the Table tree / grouped-rows / row-expansion plugins. The mirror composes correctly with the Table chevrons' state-rotation (expanded chevrons still point down under RTL). Semantic aria-labels are unchanged. - Selector & MultiSelector: add
astryx-selector-clear-icon,astryx-selector-indicator-icon,astryx-multi-selector-clear-icon, andastryx-multi-selector-indicator-icontheme targets on the clear and chevron glyphs, so consumers can recolor, resize, and hover-style each icon — and style the chevron's open/closed state — viadefineThemeinstead of a fragile descendant selector or raw CSS. Each chevron reflects its open/closed state as adata-stateattribute.Iconnow fully handles its styling props (className,style,xstyle) so they compose with its base styles instead of being dropped. Default rendering is unchanged. - add size prop (sm / md) to Switch to match CheckboxInput and RadioList boolean control scales (#4230)
- Table:
rowIndexStartandrowCountprops expose row numbering as a table-level ARIA concern, soaria-rowindex/aria-rowcountreflect a row's position in the full dataset: correct across pagination and even when no visible index column is rendered. Opt-in; tables that set neither prop are unchanged. Closes #3939. - Timestamp: new
tooltipEntriesprop renders the hover tooltip across several time zones and/or formats at once — one line per entry, each with an optionaltimezoneID(IANA id; omit it or pass'local'for the viewer's zone),format(every non-relativeTimestampFormatplus'full'), andlabel. The default is unchanged: with no entries the tooltip stays the single full absolute line in the viewer's zone. Configuring entries also attaches the tooltip to absolute formats, which previously had none — note that this gives those timestamps a tab stop and focus ring, as relative timestamps already have, so a column of them gains one tab stop per row.hasTooltip={false}still suppresses the tooltip, and an empty array counts as no configuration. Also correctsisTimezoneShown's documentation, which claimed it applied to thesystem_date_timeandsystem_timeformats; it never has, and those formats stay machine-readable. (#4188) - Token: make the
colorprop extensible via module augmentation.TokenColoris now derived from aTokenColorMapinterface, so theme packages can add custom colors (andastryx theme buildgenerates the type augmentation), matching Badge and Button. - TreeList: the per-level indentation step is now the themeable
--tree-list-indentvariable (defaultvar(--spacing-4)), so a theme can retune the indent metric viadefineThemeon thetree-listtarget instead of the previously hardcoded, unreachable step (#4308). - TreeList: add a
variantprop ('lineGuides' | 'noGuides', default'lineGuides') to select the base hierarchy guide-line look.noGuideshides the connector lines while keeping indentation intact. Orthogonal todensity(spacing); the guides stay themeable via theastryx-tree-list-guidetarget. Non-breaking — omitting the prop renders exactly as before.
Fixes
- Avatar: compose the status dot's label into the avatar's accessible name so assistive tech can reach the status the
role="img"root previously pruned (WCAG 4.1.2) - Calendar: expose selected state in day-button accessible names, announce range-selection progress and completion via the polite live region, and set aria-multiselectable on the grid in range mode
- CommandPalette: announce result counts, empty, and loading states to screen readers via the shared polite live region (WCAG 4.1.3)
- Divider: expose the label as the separator's accessible name via aria-labelledby; Spinner: name the status element from the visible label instead of duplicating it as aria-label
- FileInput: announce the required state via a visually hidden description on the trigger (aria-required is unsupported on role="button") and announce validation errors exactly once
- hooks: resolve focus-trap Escape by DOM depth instead of push order, exclude aria-hidden subtrees from trap tab cycles, and auto-clear live regions after announcing so stale status text does not linger
- List: keep list semantics for all listStyle variants by always emitting an explicit role="list", since the base style strips list-style-type for every variant and Safari/VoiceOver drops implicit list roles for such lists (WCAG 1.3.1)
- NumberInput: announce the units text through the input's accessible description, and stop TextInput/NumberInput from referencing the non-rendered status message id in aria-describedby inside InputGroup
- reset: stop suppressing
:focus-visibleoutlines on coarse-pointer devices so keyboard users keep the WCAG 2.4.7 focus indicator - hooks: auto-detect RTL direction for arrow-key navigation in useListFocus and useGridFocus (WCAG 1.3.2)
- Slider: constrain range thumb aria-valuemin/aria-valuemax by the sibling thumb (including minStepsBetweenThumbs) and render the label as a group label wired via aria-labelledby instead of an inert <label htmlFor>
- TopNav: disabled TopNavItems now render href-less anchors so they no longer navigate or fire clicks, and Outline's active item uses aria-current="location"
- Avatar: avoid remounting the avatar subtree when the name tooltip toggles — render the tooltip as a conditional sibling instead of forking the return so the avatar keeps its position in the React tree (and its image-load state) across tooltip changes.
- Card: rest the bordered variant on the subtle
--color-borderinstead of--color-border-emphasized, so a Card's outer frame matches its own LayoutHeader/LayoutFooter dividers and neighboring ClickableCards instead of rendering a heavier edge. - CheckboxInput, RadioList, Switch: align control sizes. The visible checkbox and radio controls now fill their size exactly (20px at
sm, 24px atmd) instead of being inset 2px. ThesmSwitch track is now 32px wide with a 2px inset. - Export the
BasePropstype through the@astryxdesign/core/BasePropssubpath. Previously it was only reachable through the package barrel, so theimport type {BaseProps} from '@astryxdesign/core/BaseProps'specifier thatastryx swizzlegenerates failed to resolve (#4091). - Guard DropdownMenu item hover styles with
@media (hover: hover)to prevent sticky highlights on touch devices. Forward BaseProps pass-throughs to the menu element. - FieldStatus renders a leading status icon on the
detachedmessage so status is not conveyed by color/position alone (WCAG 1.4.1). The icon is decorative for assistive tech; the message text and live-region announcement carry the status. Theattachedvariant is unchanged. - FileInput no longer nests interactive controls (the clear and status buttons) inside a role="button" trigger. The trigger is now a visually hidden button alongside them in a non-interactive container, resolving the nested-interactive a11y violation (WCAG 4.1.2) while keeping click, keyboard, and drag-and-drop behavior. (#4522)
- Inputs no longer show the hover ring while disabled. The shared input wrapper's disabled state now suppresses both the base and status hover shadows, so TextInput, TextArea, NumberInput, DateInput, TimeInput, Selector, MultiSelector, Typeahead, and Tokenizer stay visually inert on hover when disabled.
- HoverCard: move themeProps className to the layer container (where bg/radius/shadow live) so themes can target the visual surface. Forward consumer xstyle/className/style to that same layer container so surface customization lands next to the theme class, instead of silently dropping them.
- With
statusVariant="detached", bordered inputs no longer render a status icon inside the control (this also covers DateTimeInput, which is fixed to the detached presentation) — the detached message box already carries a leading icon, so the on-field glyph was a duplicate. Also centers the detached message's icon on the first line of text. - DropdownMenu/ContextMenu: mouse hover now moves the highlight instead of adding a second one, so keyboard focus and pointer hover share a single highlighted item (#4493)
- utils: clamp plainDateAddMonths to the target month's last day Adding a month to Jan 31 landed on Mar 3 (Date#setMonth overflow) instead of Feb 28, so month arithmetic from end-of-month dates skipped February entirely. The helper now uses pure month arithmetic and clamps the day, matching Temporal.PlainDate.add and date-fns.
- Calendar RTL: month-navigation chevrons now mirror correctly under RTL (via the shared
rtlStyles.mirrortransform on the nav-icon wrapper), and the range-selection / hover-preview fill pills use logical CSS (insetInline*,border*Start/EndRadius) so their rounded start/end caps follow the reading direction instead of the physical left/right. LTR rendering is unchanged. - Carousel now supports RTL: the directional scroll-button chevrons mirror under RTL, the scroll buttons respect RTL scroll semantics (previously the button was a no-op under RTL), and the button pills sit on the correct edges.
- RTL: migrate physical
left/rightCSS properties to their logical equivalents so components mirror correctly underdir="rtl". This is the Phase 2 mechanical, one-to-one follow-up to the RTL direction API — a no-op in the default LTR direction with no visual change. - RTL Phase 4 (behavioral): mirror directional behavior that logical-CSS and icon name-swaps alone couldn't fix. SideNavCollapseButton and TreeListItem now compose
rtlStyles.mirroron the icon wrapper outside the state rotation, so the chevrons point toward the correct edge in every collapsed/expanded × LTR/RTL combination. TreeList connector/guide lines position via logicalinset-inline-start/inset-inline-endso they mirror to the inline-start (right) edge under RTL alongside the chevron and row indent. Slider positions its thumb, fill, and marks via logicalinset-inline-startand flips the physical centering transform under RTL, and its pointer/click math measures the value fraction from the inline-start (right) edge under RTL — so a click at 25% of the track maps to 75 instead of 25. - RTL Phase 4b behavioral fixes: ChatMessageBubble grouped-bubble tail corners now use logical border radii so the tail follows reading direction (mirrors under RTL, text unaffected); Table sticky-column shadows make their
translateXand gradient direction-aware so the shadow fades from the pinned edge toward scrolled content in both LTR and RTL instead of rendering inside-out, and gate shadow visibility onMath.abs(scrollLeft)so the start/end shadows still appear under RTL (where spec-compliant browsers report a negativescrollLeft); ResizeHandle's hit-area bias is now direction-aware (mirrors about center under RTL) and the pointer-drag delta reads the handle's computed direction so dragging resizes intuitively in RTL. - Markdown honors the
components.imageoverride for standalone (block) images, matching the inline image path. A standaloneline parses as a block image, whose render path previously hardcoded a bare<img>and ignored a suppliedcomponents.image; it now uses the override just like an inline image does. - Selector & MultiSelector: keep group headers visible while searching; hide groups with no matching items. Previously, typing a query flattened grouped options into a single ungrouped list; now each group header stays above its matching items and a group is hidden only when none of its items match.
- SideNav: remove the top border above the footer region so the
footerslot no longer renders a divider line. - Slider: round snapped values to the min/step decimal precision
With fractional steps,
min + steps * stepaccumulated binary floating-point error, so a keyboard nudge on astep={0.1}slider emitted0.30000000000000004throughonChange/onChangeEnd(and intoaria-valuenow/the value tooltip once the consumer echoed it back). Snapped values are now rounded to the combined decimal precision ofminandstep, which removes only the error — exact steps are unaffected. - Tooltip: dismiss the tooltip when its trigger is pressed. Previously the tooltip stayed open through a click (e.g. a "Copy link" button's tooltip lingered after activation); now pressing the trigger hides its own tooltip. Applies to uncontrolled tooltips only.
- Typeahead: omit aria-activedescendant when search results are empty or index is out of bounds (#4059)
Documentation
- document
widthprop across 17 input component doc files (#4163)
Other Changes
- Add
@astryx/no-physical-propertiesESLint rule that flags physical left/right CSS properties insidestylex.create()and suggests the CSS logical equivalent for RTL support. - KEY-BASED:
marginLeft/marginRight,paddingLeft/paddingRight,borderLeft/borderRight(+ theirWidth/Style/Colorlonghands),left/right→insetInlineStart/insetInlineEnd, and the four physical corner radii → their diagonal-aware logical names (borderTopLeftRadius→borderStartStartRadius, etc.). - VALUE-BASED:
textAlign: 'left'|'right',float: 'left'|'right', andclear: 'left'|'right'(the key stays, only the physical value is flagged). - Scoped strictly to
stylex.create()— physical identifiers used elsewhere are ignored. useDirection()returns'ltr' | 'rtl'for the current provider context (falls back to'ltr'when called outside a provider).getLocaleDirection(locale)computes direction from a BCP 47 locale viaIntl.Locale.getTextInfo()— safe to call from React Server Components and Next.js layouts to set<html dir>.<InternationalizationProvider locale="ar">auto-derivesdir="rtl". Pass an explicitdirprop to override (useful for RTL testing under an English catalog, or to force LTR).- Pagination is the first component to consume the hook: prev/next chevron icons flip under RTL while the aria-labels stay semantic.
- Storybook gains a global
Directiontoolbar for toggling every story between LTR and RTL. - Component-level CSS migrations (borders, chevrons, sliders, calendar range pills, etc.) land in follow-up PRs.
textAlign: 'left' | 'right'→'start' | 'end'(Selector, Typeahead, Chat trigger menu, DropdownMenu, CommandPalette, NavMenu items).borderLeft*/borderRight*→borderInlineStart*/borderInlineEnd*, kept as separate start/end declarations (Banner, Table cell/header dividers, DateRangeInput preset sidebar).- Static
left/rightpositioning →insetInlineStart/insetInlineEndfor full-bleed overlays and single-side offsets (Button spinner overlay, Chat dock/blur/placeholder, Field sr-only label, Lightbox close/nav/counter buttons, TabList indicators, Thumbnail remove slot, CodeBlock copy button). - Inline
marginLeftindentation →marginInlineStart(TreeList rows).
Contributors
Thanks to everyone who contributed to this release:
0.1.9
New Features
- Avatar: add a
tooltip?: string | booleanprop for a name-on-hover tooltip. Omitting it (ortrue) shows the avatar'snameon hover and keyboard focus; a string shows that text instead (no need to wrap inTooltip);falsedisables it. Avatar owns the tooltip via the existing Tooltip hook, so there's no extra wrapper DOM. Because this adds a default tooltip to every existing named Avatar, settooltip={false}when you supply your ownTooltip/HoverCardoverlay. The rootaria-label(alt || name) is unchanged; the default name tooltip is visual-only (noaria-describedbydouble-announce), while a custom string tooltip is exposed as a description. Decorative avatars (noname/alt) get no tooltip. (#4164) - BreadcrumbItem gains a
menuprop that turns a crumb into a menu trigger for switching between sibling destinations. It accepts the same item API as DropdownMenu/MoreMenu/ContextMenu (aDropdownMenuOption[]array or composed item children), so existing menu-item definitions drop into a breadcrumb with no rewrite. The item components are also re-exported underBreadcrumb*aliases. - Calendar: make the today/selected day-cell ring precisely themeable. The day cell now reflects a compound
markerstate (today-only/today-in-range) that maps 1:1 to the treatment actually drawn, sodefineTheme({components: {'calendar-day': {'marker:today-only': {...}}}})targets exactly those states without over-matching or needing a:not()exclusion. Default rendering is unchanged. - Calendar: add a dedicated
astryx-calendar-navtheme target for the prev/next month-nav buttons, so consumers can theme the nav controls (color, radius, per-direction, disabled edge) without reaching every Button via the globalastryx-buttonhandle. Reflectsnav(prev/next) and thedisabledstate as data attributes. - ChatComposer: make custom inputs first-class.
useChatComposerContext()and its types are now public, so any input in theinputslot can readvalue/onChange/onSubmit/canSend/placeholder/isDisabledand drive the shell's send button. Inputs can register a focus control oninputControlRefso click-to-focus works for any input shape (not justcontenteditable/textarea); the shell keeps a DOM-query fallback for uninstrumented inputs. - ChatComposerInput: add an
onKeyDownseam so consumers can host platform- or app-specific key handling — e.g.preventDefault()Enter to insert a newline on a touch keyboard, or submit on Cmd/Ctrl+Enter. Enter also no longer submits mid-IME-composition. - CommandPalette: add a dedicated
astryx-command-palette-group-headingtheme target on the group heading, so consumers can theme just the heading (e.g. its padding or typography) viadefineThemeinstead of a fragile structural selector. The group root keeps its ownastryx-command-palette-grouptarget. - DateInput gains a
formatprop for the committed date value, reusing Timestamp'sformatvocabulary so the same literal renders the same date shape in both components. Named values aredate_long(the default, "March 21, 2026"),date("Mar 21, 2026"),date_weekday("Wed, Mar 21, 2026"), andsystem_date("2026-03-21"); a(value) => stringfunction is also accepted for custom output. Thedate_longdefault is byte-identical to DateInput's previous long-month rendering, so existing usage is unchanged. This also extends Timestamp with two new shared members,date_longanddate_weekday, giving the two components full value parity on the date-only formats. Formatting applies only to the committed value, never to text being typed. - Add an
elevationprop to configurable surfaces — Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner take the full'none' | 'low' | 'med' | 'high'scale; ChatComposer takes'none' | 'low'. Defaults preserve today's appearance (noneeverywhere except ChatComposer'slow), so nothing changes unless you opt in. (#4146) - OverflowList: add
maxVisibleItemsto cap the number of visible items (the ceiling partner tominVisibleItems) andmaxRowsfor bounded multi-row wrapping — items wrap onto up to N rows, then collapse into the overflow indicator. Both props are optional and default to off, so single-line behavior is unchanged. See #4176. - Add
useTableRowStatus, a plugin that prepends a narrow column signaling per-row status. - Thumbnail: add
showRemoveOnprop —'hover'(default) reveals the remove button on hover or keyboard focus and keeps it visible on touch;'always'shows it at rest. - Table tree: add an optional expand-all/collapse-all header control (#4142)
useTableTreeStatenow returns an aggregateisAllExpandedstate (true/false/'indeterminate') and threadsexpandAll/collapseAllintotreeConfig.useTableTreeDatagains ahasExpandAllControlprop: when set, it renders an expand-all/collapse-all toggle in the tree column header, wired to that state, so consumers no longer need to hand-roll external buttons. Flat data stays a full no-op. This is the first affordance folded in fromuseTableRowExpansionas part of converging the two tree plugins. - TreeList: add a dedicated
astryx-tree-list-chevrontheme target for the expand/collapse toggle, so consumers can theme the chevron (color, per open/closed state) viadefineThemeinstead of reaching it through the functional[data-tree-toggle]attribute. Reflects the open/closed state as adata-stateattribute (expanded/collapsed); the functionaldata-tree-togglehook is unchanged. - TreeList: add a stable
astryx-tree-list-guidetheme target on the hierarchy guide (connector) line elements, so consumers can recolor or hide the guides throughdefineTheme(e.g.backgroundColor, ordisplay: 'none'to hide them) instead of hiding the built-in connectors and reimplementing them with unlayered CSS. - TreeList: add a dedicated
astryx-tree-list-item-labeltheme target on the item's label text, so consumers can theme just the label (e.g. bold the selected item's label) viadefineThemeinstead of a fragilebutton:not([data-tree-toggle]) > spanstructural selector. Reflects the row'sselectedstate as adata-selectedattribute on the label.
Fixes
- AvatarStatusDot: pair each variant with a distinct built-in shape — success stays a filled dot, neutral renders as a ring, error gets a minus bar — so status no longer relies on colour alone (WCAG 2.1 SC 1.4.1, #4143). A rendered
iconreplaces the shape glyph at sizes where icons fit; themes can target the new stableastryx-avatar-status-dot-glyphclass and itsdata-shapeattribute — a stroked inline<svg>painted from the dot'scurrentColor. - Button: link-rendered buttons (
href) now exposearia-busywhile loading, matching the<button>branch. Previously an interruptible loading link showed the spinner and announced "Loading" but carried no machine-readable busy state. - Calendar only marks in-month date cells as today, preventing duplicate today indicators in multi-month views.
- Carousel: slides now expose APG slide semantics (role=group, aria-roledescription="slide", "Slide N of M" labels) instead of anonymous divs.
- Honor
prefers-reduced-motionin ChatToolCalls (chevron rotation, expand/collapse), ChatLayoutScrollButton (pill show/hide), and ChatDictationButton (equalizer bars). - Chat/useChatStreamScroll: the scroll-follow spring now respects
prefers-reduced-motion— locked following,scrollToBottom(), andlock()fall back to the existing instant jump, so the transcript still tracks the bottom without animated travel. Follow-up promised in #3800. - Chat: the composer drawer toggle now references its disclosed content via aria-controls, so assistive tech can navigate from the toggle to the drawer.
- ChatSendButton now forwards
className,style, and pass-through attributes (data-*,aria-*, and other rest props) to the rendered button. Previously these were silently dropped. (#4190) - Chat: tool-call error details are now exposed to screen readers and keyboard users instead of living only in a hover-only title attribute.
- CheckboxInput: the indeterminate mark now uses the
--radius-fulltoken instead of a hardcoded radius, for token consistency. No visual change. - CheckboxList: items with rich (non-string) labels can now provide an accessibleLabel so their checkbox no longer announces as the literal "Checkbox".
- CodeBlock: collapsed code regions are now inert, so keyboard focus can no longer land on the invisible scroll container while collapsed.
- CommandPalette: forward BaseProps pass-through attributes (className, style, xstyle, data-, aria-) to the underlying Dialog. Previously these were silently dropped.
- CommandPalette: the search input (role=combobox) now has an accessible name by default, from the new label prop or the visible placeholder. Previously screen readers announced a nameless combobox.
- DateTimeInput: ArrowDown (and Alt+ArrowDown) in the date field now opens the calendar popover from the keyboard, matching DateInput and the advertised combobox pattern.
- Dialog: modals are now automatically labelled by their DialogHeader title via aria-labelledby, matching AlertDialog. Unnamed open dialogs warn in development.
- Dialog: the entry animation is disabled under prefers-reduced-motion, matching the Layer animation guards.
- Fix Divider rest-prop spread order so consumer-passed HTML attributes cannot overwrite the component's
role="separator"oraria-orientation. - FieldLabel now forwards className, style, xstyle, and pass-through attributes (data-, aria-, event handlers) to the rendered element. Previously these were accepted by the type but silently dropped.
- Field/FieldStatus: status and error messages are now announced through persistent live regions, so they are reliably read by screen readers regardless of when they appear.
- FileInput: the trigger's accessible name now includes the selected filenames, so screen-reader users can review what is attached when refocusing the control.
- Prevent PowerSearch edit popover from closing when selecting multi-select options via Enter (#4245)
- Selector/MultiSelector: PageUp/PageDown now jump the active option to the first/last match while searching, complementing Home/End which stay on text-caret movement.
- HoverCard: popups now expose a named dialog when the new label prop is set, and honest group semantics otherwise. Previously every hover card announced as an unnamed dialog.
- Item: aria-selected is now emitted only when the item's role permits it (option, tab, treeitem, grid cells), removing invalid ARIA from plain list items.
- MobileNav: the toggle button now exposes
aria-expandedand references the nav drawer viaaria-controls, so screen-reader users can tell whether the drawer is open and what the button controls. (#3721) - MultiSelector: searching within the options popover now announces the number of matching results ("3 results" / "No results found") to screen readers, mirroring Selector and Typeahead. Previously filtering happened silently.
- SideNav/TopNav: collapsed heading popovers no longer wrap their menus in a modal dialog, and the heading button is no longer an invalid child of the menu.
- Slider now clamps controlled values to its minimum and maximum before positioning the thumb and exposing ARIA values.
- Slider: required sliders now convey the required state to screen readers through the thumb's accessible description (aria-required is invalid on the slider role).
- Make the CLI's
.mjssources fully strict-typecheckable (checkJs + JSDoc) Annotated the entire CLI package sotsconfig.strict.json(fullstrictcheckJsoversrc,bin,scripts,docs, and the emittedtemplates) reports zero errors — down from 1717. Fixes are JSDoc-only: no runtime logic changed,.mjsstays.mjs. Strict checking also surfaced and corrected several type-contract drifts: theupgrade.runresponse type (declared adepsUpdatedfield the command never emits, and omitted the realintegrations/filesChanged/transformsApplied/errors), registered the emittedtheme.list/theme.add/layout.*response types in the--jsonenvelope union, and addedcategory?toReferenceSectionin core's docs types (reference docs already emit it). - Table: the selection plugin accepts getRowLabel so row checkboxes announce which row they select, instead of an undifferentiated "Select row".
- Text: an explicit
sizenow overrides the font-size of a themedtype. Thesizeclass lived in a lower cascade layer (astryx-base) than a theme's per-type font-size rule (astryx-theme), so<Text type="supporting" size="xsm">silently kept the type's size. Themes now re-emit the size classes in the theme layer sosizewins as documented. - Thumbnail: replace the hover box-shadow on interactive tiles with the same
::afteroverlay treatment ClickableCard and SelectableCard use. All three now tint on hover with--color-overlay-hover(and--color-overlay-pressedon press), so interactive feedback is consistent across the card family. - Thumbnail/TopNavMegaMenuFeaturedCard: images without alt text are now explicitly decorative instead of silently empty-alt, matching Avatar's handling.
- Thumbnail: the overlaid remove button now uses a fixed
--color-overlayscrim with an--color-on-darkicon instead of adapting to the image's luminance, so it has reliable contrast on any image. - Tokenizer: adding and removing tokens (including Backspace on an empty input) is now announced to screen readers. Previously tokens appeared and disappeared silently.
- TopNav: TopNavMegaMenu triggers now expose aria-controls, and the panel is a labeled group instead of an invalid modal-dialog-wrapped menu.
- TopNav: TopNavMenu popups now expose proper menu semantics (no modal dialog wrapper) with the full APG keyboard pattern (roving tabindex, arrow keys, typeahead).
Documentation
- docs(Tokenizer, PowerSearch): document and test the existing startIcon propBoth components have shipped a working
startIcon?: ReactNode | IconTypeprop for a while (PowerSearchforwards it verbatim to the internalTokenizer, and it's already exercised in Storybook), but neither's.doc.mjsdocumented it and neither had test coverage — so it was invisible toastryx component <Name> --dense, the docsite props table, and anyone (human or AI) relying on those as the source of truth. No behavior change; adds the missing props-table entries (en/zh/dense) and colocated tests confirming the icon renders and forwards correctly.
Other Changes
- Compact per-row status signal (error, warning, unread, etc.) without a dedicated status column: a colored status dot by default, or an icon when provided.
getStatus(item)maps a row to{color, icon?, label?}, ornullfor no indicator.coloraccepts a semantic status name (success/error/warning/accent/red/green/etc.) mapped to a theme token, or a raw CSS color as an escape hatch.iconrenders the status as a shape signifier instead of the dot, which is more accessible than color alone when multiple statuses coexist.labelsupplies the accessible name.- Memoize
getStatuswithuseCallbackfor a stable plugin identity.
Contributors
Thanks to everyone who contributed to this release:
0.1.8
Breaking Changes
- Avatar and AvatarGroup adopt Icon's abbreviated size scale —
sizenow takesxsm/sm/md/lg/xlinstead oftiny/xsmall/small/medium/large. Pixel values are unchanged (20/24/36/48/128px) and the default is nowmd(still 36px, formerlysmall). Avatar's tiers stay larger than Icon's because avatars align with media rather than glyphs. Runastryx upgradeto migrate call sites. (#2672)
New Features
- Collapsible: the content area now anchors body typography (font family, size, weight, line-height) instead of inheriting from its surroundings, and exposes a stable
astryx-collapsible-contenttheme target so revealed text can be themed externally. - Collapsible: add an
isDisabledprop to disable a single item. A disabled item's trigger can't be toggled and is dimmed; following the system-wide disabled convention it usesaria-disabled(not the nativedisabledattribute) and drops out of the tab order, staying perceivable to assistive tech. Disabling doesn't collapse an already-open item. Works standalone and inside CollapsibleGroup. @astryxdesign/core'sdocs.mjsnow redirects to the CLI so agents converge on a single documentation entry point (astryx docs/astryx init) instead of a large standalone script. (#4207)- DropdownMenu selectable items: add
DropdownMenuCheckboxItem(independent toggle,role="menuitemcheckbox") andDropdownMenuRadioGroup+DropdownMenuRadioItem(single-select,role="menuitemradio"). The control size derives from the menu's item size and swaps to the row's inline-end on touch. They also work insideContextMenu(re-exported asContextMenuCheckboxItem/ContextMenuRadioGroup/ContextMenuRadioItem). Both menus' keyboard/typeahead/activation now recognize the selectable roles, and the menu context (DropdownMenuContext,useDropdownMenuContext,DropdownMenuSize) is exported for building custom menu items. See #3829. - Icon: add an optional
labelprop for the accessible name. Setting it makes a standalone icon meaningful (role="img"+aria-label, noaria-hidden), collapsing the old three-attribute dance into one prop; omitting it (or passing'') keeps the decorative default (aria-hidden). - "Foolproof init": both
@astryxdesign/coreand@astryxdesign/clinow print a postinstall nudge pointing you tonpx @astryxdesign/cli init,astryxcommands nudge you to finish setup until init has run, andastryx initruns non-interactively (no TTY required) so it works in CI and agent environments. (#4147, #4153, #4154, #4155) - Outline: keyboard navigation, navigate callbacks, and scroll-scoping props (#2527) Layers the public API deferred out of #2746 onto the scroll-spy engine and click-lock that already shipped. No visual change.
- Table: add a tree-data plugin —
useTableTreeStateanduseTableTreeData— for rendering and managing hierarchical (parent/child) rows, expansion state, and flattening. Exported from@astryxdesign/core/Table. (#3789)
Fixes
AvatarGroupOverflownow grows into a pill for long+Ncounts so the number never clips. The indicator was a fixed-size circle, so wide counts (e.g.+4912) overflowed and crowded the edges. It now uses a minimum width equal to the avatar size plus horizontal padding: short counts (+5) stay a perfect circle, while longer counts grow horizontally into a stadium/pill and remain legible. No new public props.- Carousel now scrolls horizontally when you hold Shift and scroll the mouse wheel. Trackpad users already got horizontal scroll for free; this brings standard mouse (vertical-only wheel) users to parity using the established Shift + wheel convention. Native trackpad horizontal scrolling and the prev/next buttons are unchanged.
- Citation: a non-interactive citation (no
source.url) now keeps the default cursor instead of showing a pointer, so only linked citations look clickable. The pointer cursor is applied alongside the existing hover treatment for both thelabelandnumbervariants (#4134). - Stop suggesting bare
npx astryxbefore the CLI is installed — it resolves to an unrelated package on the npm registry. The CLI now emits an install-aware invocation everywhere it prints a command: - Icon: size variants (
xsm/sm/md/lg) now usereminstead of hardcodedpx, so icons scale in step with text when the document/rootfont-sizechanges — matching the rest of the design system's rem-based type scale. Fixes #4092. - Guard useTableRowExpansionState tree walks against cyclic data (#3971)
The
depthMap, flatteneddata, andallExpandableKeyswalks now track the ancestor keys on the current path and skip edges that point back at an ancestor, so self-referential or cyclic row data terminates instead of overflowing the stack. - Route the Table sortable plugin's header-button aria-labels ("Sort by …", "… sorted …", "… priority … of …") through
useTranslator()with new@astryx.table.sort.sortBy/sortedBy/sortedByWithPriority/direction.*catalog keys, so they localize like the sort menu labels already do (#3618, tracker #3636). The direction word resolves through its own key rather than interpolating the raw enum value. English output is unchanged. - Table: the tree row expander's
aria-labelis now localized throughuseTranslator()instead of a hardcoded English string, so expand/collapse controls announce in the app's language. (#4149) - TabList
hasDividerreserves a gap so the hover pill and adjacent buttons no longer touch the underline A divided TabList now reserves 4px between the tabs and the divider rail. The hover highlight sits clear of the underline, and a same-size Button placed alongside the tabs aligns to the tab baseline instead of butting the rail — so amdtab strip pairs with amdbutton. The selected indicator still rests on the rail. Non-divided tab lists are unchanged. TabList inside aToolbarwithdividers={['bottom']}gets the same alignment via the toolbar's own spacing. - TreeList: focusing a parent row no longer leaks the focus-visible outline onto its descendant rows — each row's ring now resolves from its own nearest treeitem instead of matching any focused ancestor (#4130)
Documentation
- DropdownMenu and DropdownMenuItem: seed playground defaults so the docsite properties-tab preview renders real content instead of an empty trigger.
Other Changes
- Installed / global / dev runs suggest
<pm> astryx <cmd>(e.g.pnpm exec astryx …), unchanged. - One-off runs (launched via
npx/pnpm dlx/yarn dlx/bunx) suggest the scoped package<dlx> @astryxdesign/cli <cmd>, which always resolves to us. - Improved translator context in the shipped English catalog (
packages/core/locales/en.json) descriptions. Sharpened ~172 entries — added screen-reader-only clarifications, ICU-composition examples, polysemy warnings, and set-pairing notes — so translators working in Crowdin get better context. No changes todefaultMessagevalues, keys, or runtime API. - Keyboard navigation — the outline is now a single tab stop (roving tabindex via
useListFocus), seated on the active heading per WAI-ARIA, so tabbing into a table of contents while reading section 7 lands on section 7 rather than sending the reader back to section 1. Arrow keys move between headings, Home/End jump to the ends, and Enter/Space activate. A 40-heading table of contents costs one Tab press instead of 40, and Tab still leaves the outline in one press. onNavigateStart(id)/onNavigateEnd(id)— fire around the smooth scroll started by a click or keyboard activation, so an app can drive an arrival effect.onNavigateEndresolves onscrollendwhere supported and on a settle timeout where it is not (Safari), so it also fires correctly when reduced motion collapses the scroll into an instant jump. It fires exactly once for everyonNavigateStart— including when the user interrupts the scroll — so a "navigating" state can never leak.offset— the height of a fixed header overlaying the top of the scroll root. It shifts both the activation line and the scroll landing by the same amount, so a heading activates exactly where navigating to it puts it: below the header, not hidden underneath it. It composes with each heading's ownscroll-margin-top(the header, then the breathing room below it) rather than replacing it — leaveoffsetat 0 when nothing overlays the content and letscroll-margin-topdo the work, since the browser already honors it.scrollContainerRef— scope scroll tracking to a specific container instead of auto-detecting the nearest scrollable ancestor. Fixes the table of contents whose highlight never moves inside a split pane, modal, or dashboard panel. The default (viewport) path is unchanged.hasScrollOnClick(defaulttrue) — set tofalseto own the scrolling yourself; the outline still updates the active item, the hash, and the navigate callbacks.
Contributors
Thanks to everyone who contributed to this release:
0.1.7
Breaking Changes
- Table plugin render-prop interfaces (
TableRenderProps,HeaderRowRenderProps,HeaderCellRenderProps,BodyRowRenderProps,BodyCellRenderProps,ScrollWrapperRenderProps) and thescrollWrappercomponent contract rename their StyleX array fieldstyles→xstyle, matching the prop name sub-components receive it under. Custom plugin authors: renameprops.stylesreads andstyles:writes in transform functions (#3679) Codemod:npx astryx upgrade --codemod rename-table-renderprops-styles-to-xstyle
New Features
- Export the authoring factories from
@astryxdesign/core:createConfigat@astryxdesign/core/configandcreateIntegration/createPageTemplate/createBlockTemplate/createComponentDoc/createFunctionDoc/createDocat@astryxdesign/core/authoring. Authoring a config or integration no longer requires depending on the CLI. Existing@astryxdesign/cli/*imports keep working via re-export. - Button: new
widthprop following the input field width convention (SizeValue: numbers are pixels, strings are used as-is).width="100%"removes the need for awidth: '100%'xstyle override or a stretch layout wrapper for full-width CTAs in auth forms, dialogs, and mobile layouts (#2600). - Astryx components are now translatable. Wrap your app in
<InternationalizationProvider locale="...">and pass one or more locale catalogs to render astryx UI in the language of your choice; calluseTranslator()inside your own components to translate consumer strings against the active locale. Astryx ships an English catalog with BCP 47 regional fallback (e.g.pt-BR→pt→en), so consumers who never render a provider see today's English strings unchanged. - Translation coverage now spans the full component set — PowerSearch (UI chrome, value-editor labels/placeholders, the 21 built-in operator labels, and ICU-pluralized result counts), plus AlertDialog, AppShell, Banner, Breadcrumbs, Calendar, Chat, CommandPalette, ContextMenu, date/time inputs, Dialog, DropdownMenu, Lightbox, Link, Markdown, mobile/side/top nav, Outline, Popover, Resizable, Selector/MultiSelector, Table (and its filter/selection/sort plugins), Toast, Tokenizer, Typeahead, and related interactive affordances. Placeholder strings that used
...are normalized to…(U+2026) in the English catalog; consumers who snapshot-test the exact three-dot form will see a diff, and consumers passing an explicitplaceholderare unaffected. - Two i18n-related type refinements (source-compatible for existing usage):
PowerSearchOperatoris now a discriminated union —{key, value, label}(raw text) or{key, value, i18nKey}(astryx-translated); passinglabelcompiles and behaves unchanged, while a bare{key, value}(neitherlabelnori18nKey) becomes a compile-time error.Markdown.renderBlockgains at: TranslatorFnparameter threaded from the top-levelMarkdown; directrenderBlockconsumers pass a translator. - New ESLint rules in
@astryx/eslint-plugin-astryx(astryx.configs.strict/recommended):@astryx/i18n-key-formatenforces camelCase path segments for@astryx.*catalog keys, and@astryx/no-hardcoded-i18n-stringflags hardcoded English string literals on user-facing props — now also inside ternaries, logical expressions, and template literals (e.g.aria-label={isOpen ? 'Close' : 'Open'}). Both are filesystem-agnostic; downstream packages can enable them with the standardfiles/ignorespattern and will see additional violations flagged after upgrading.
Fixes
- Fix Banner chevron transition to honor
prefers-reduced-motion: reduce. - Round the trailing corner of the last ButtonGroup member, even when it renders a layer (#2508)
ButtonGroup keyed its trailing border-radius off
:last-child. But several members render an invisible layer element after their button — aButtonwith atooltipreturnsbutton + tooltip layer, andDropdownMenureturnstrigger + popover, both rendered inline byuseLayerrather than portaled. The layer took the:last-childslot, so the real trailing button silently kept square outer corners and the group ended in a flat-edged stub. - Calendar: month navigation now announces the newly visible month (e.g. "March 2026") to screen readers via a polite live region. Previously the grid changed silently. (#3724)
- Chat: opening a conversation that already has content (history, replay, session switching) no longer spring-scrolls from the top — the first fill positions instantly, whether the content is present at mount or arrives asynchronously. Subsequent growth (streaming) springs as before.
useChatStreamScroll'sscrollToBottomaccepts{behavior: 'instant'}for one-frame programmatic jumps, mirroring the DOM'sscrollTo({behavior}). Exports theChatScrollToBottomOptionstype. (#3795) - CheckboxInput/Switch: descriptions stay linked via aria-describedby when the label is visually hidden, instead of being orphaned in the DOM.
- CodeBlock keeps line numbers aligned with wrapped lines when
isWrappedis enabled - Forward rest props in Dialog and DialogHeader. DialogHeader now passes through data-testid, aria-*, and other attributes. Dialog's inline path forwards all rest props. Standard path spreads rest before contract props so onClick, onCancel, aria-modal, and role cannot be clobbered.
- Anchor --dense / --zh doc overlays to their base sections (#2182) The compressed and translated reference docs were merged into the base doc by array position, so an overlay whose sections were ordered differently — or which omitted one — grafted every title onto the wrong body.
- FileInput: don't drop the drag-over highlight when dragging over dropzone children Dragging a file across the dropzone's own icon/text fired a dragleave on the container and cleared the drag-over state, so the "Drop files here" highlight flickered mid-drag. A dragleave whose relatedTarget is still inside the dropzone is now ignored; only actually exiting the dropzone ends the drag-over state.
- Fix consumer rest props clobbering component contract props in ButtonGroup, Calendar, and Carousel
Components that set
role,aria-roledescription, oronKeyDownon their root element now spread{...rest}before those props so a consumer cannot accidentally override the component's semantic contract.onKeyDownis composed viacomposeEventHandlersso both the consumer's and the component's handlers fire. - Kbd: pass-through props no longer clobber the computed role and spoken accessible name (rest-spread precedence corrected, mirroring Avatar).
- Layer: centered layers near a viewport edge no longer render clipped (#3671). Flip fallbacks are a no-op for center alignment, so centered placements now append span-based
position-try-fallbacksthat slide the layer along its alignment axis. - Link: disabled links no longer carry a live href/onClick — programmatic focus or AT activation can no longer trigger navigation.
- Selector: searching within the options popover now announces the number of matching results ("3 results" / "No results found") to screen readers, mirroring Typeahead. Previously filtering happened silently. (#3725)
- Table now honors the standard root styling props:
className,style,xstyle,id,aria-*,data-*, and other HTML attributes reach the root<table>element instead of being silently dropped.tablePropsis deprecated (still works, loses conflicts to direct props); the computed column min-width still wins over a consumerstyle.minWidth, but no longer clobbers it when columns compute none (#3679) - Timestamp: the absolute-time tooltip is now reachable by keyboard — the timestamp is focusable while a tooltip is attached, per WCAG content-on-hover requirements.
- TopNav: the
<nav>landmark now defaults its accessible name to "Top navigation" when thelabelprop is omitted, matching SideNav ("Side navigation"), Breadcrumbs, and Pagination. Previously an omittedlabelshipped an unnamed navigation landmark, leaving screen-reader users with multiple indistinguishable "navigation" landmarks on pages that compose SideNav + TopNav + Breadcrumbs. An explicitlabelstill wins.
Documentation
- Point AI agents to the CLI from the core README.
@astryxdesign/core's README now leads with a callout telling AI agents to runnpx astryx initfirst, which installs the CLI's component index intoAGENTS.md/CLAUDE.md. In an isolated cold-start test, this took agents from 0/5 to 4/5 on discovering and using the CLI (matching the AGENTS.md ceiling); a first-run nudge alone did 0/5. - Surface literal values for union types in component docs (#1645)
Prop docs named their union types without ever showing the values behind them —
gap: SpacingStep,align: GridAlignment,sort: TableSortState<TSortKey>,status: InputStatus. Readers without an IDE (agents especially) had to guess, and guessed wrong:gap={16}(pixels, not a scale step),direction: 'desc'(the type says'descending').
Other Changes
- Migrate the duplicated charts/lab color parsers onto the shared
@astryxdesign/core/utils/colormodule: addstoGLFloats(rgba)for RGBA→GL float conversion with a neutral non-NaN fallback, replacing the fourhexToGLcopies, and rebuildslerpHex/hexAlphaonparseHex/formatHex/parseColor/formatColor(#3739)
Contributors
Thanks to everyone who contributed to this release:
0.1.6
New Features
- Add
useTableGroupedRows— groups a flat data array into collapsible section rows. Each distinctgroupByvalue becomes a full-width section-header row with a chevron toggle, group label, and member count; collapsing hides that group's rows while keeping the header. MirrorsuseTableRowExpansionState: the consumer owns thecollapsedGroupsset and the hook returns{data, plugin, idKey}(pass toTabledata / plugins / idKey). SupportsrenderGroupHeaderandgroupOrder. (#3763) - Add
useTableRowIndex— a plugin that prepends a right-aligned, monospaced row-number column. Numbering follows the rendereddataorder, so it reflects the current sort / filter / pagination view (pass the sorted/paged array). ProvidesgetRowKeyfor stable keyed lookup, pluslabelandstartFromto customize the header and starting ordinal. (#3756)
Fixes
- Rebrand the core package
displayNamefrom "XDS Core" to "Astryx Core" The core package'sdisplayNamestill read "XDS Core". It surfaces in the docsite package sidebar and landing cards as the friendly package label, so this rebrands it to "Astryx Core" to match the Astryx migration. Metadata-only — the packagenameand public API are unchanged. - Compile dist with the production JSX transform — 0.1.5 shipped
jsxDEV, which crashes every consumer that renders in production@babel/preset-react8 derives itsdevelopmentoption from the Babel env name (api.env(env => env === 'development')), and Babel falls back to"development"wheneverNODE_ENV/BABEL_ENVis unset. The bump from 7.29.7 to 8.0.1 therefore flipped the published build to the development JSX transform without any config change: 193 of 479 files in@astryxdesign/core@0.1.5'sdistimportreact/jsx-dev-runtimeand calljsxDEV, which React's production build does not export.
Contributors
Thanks to everyone who contributed to this release: