What's New
Release notes and changelog for all packages.0.5.0
Breaking Changes
- Banner: the collapse axis moves onto one
collapsibleprop, and content can opt out of collapsing (#5255) Banner inferred its disclosure from its content: anychildrengot a chevron in the header and were hidden until it was pressed. There was no way to show content without a toggle — the case a banner most often wants, a list of the three fields that failed validation — anddefaultIsExpandedwas the only knob, with no controlled mode.The whole axis is now oneboolean | CollapsibleConfigprop, following the boolean-or-config conventionSideNav.collapsibleset, and backed by the shareduseCollapsiblehook rather than Banner's own state:tsx<Banner status="error" title="3 fields need attention">…</Banner> // unchanged: collapsible, starts closed<Banner collapsible={false}>…</Banner> // new: always visible, no toggle<Banner collapsible={{defaultIsOpen: true}}>…</Banner> // replaces defaultIsExpanded<Banner collapsible={{isOpen, onOpenChange}}>…</Banner> // new: controlledThe default is unchanged — a banner that never mentioneddefaultIsExpandedbehaves exactly as it did. The breaking part is the prop itself:defaultIsExpandedis removed in favour of the config, which is a type error at every JSX call site that names it.Codemod:npx astryx upgrade --codemod banner-collapsible-contentIt rewritesdefaultIsExpandedtocollapsible={{defaultIsOpen: true}}and dropsdefaultIsExpanded={false}, which is now the default. Banners that never set the prop are left alone.One case the codemod and the compiler both miss: a spread.defaultIsExpandedinside a props object is out of the transform's scope. A props object in a typed position still fails to compile — but an inferred one that is spread,<Banner {...args} />, does not, because TypeScript does not excess-property-check a spread. The prop then falls through to the DOM and the banner quietly starts collapsed. Grep fordefaultIsExpandedafter running the codemod and migrate any spread sites by hand.
New Components
- Promote
StepperandStepfrom the canary-only Lab package to Core. The stable package now ships their existing horizontal/vertical layouts, separated and on-track indicators, semantic status, density, and non-linear navigation, plus Core documentation and rendered examples. The defaultaria-labelis now localized. Advancing one step now animates the connector. Every connector the four layouts draw — the separated bars and the on-track segments alike — grows its accent fill out of the segment's leading edge instead of swapping a background color, so moving forward reads as progress travelling the track. That one gesture is the only thing that animates: going back, jumping forward by more than one step, and mounting mid-flow all apply at once, as does any change underprefers-reduced-motion. Retreats are deliberately instant — run in reverse the same transition ends on a shrinking stub of accent, and a remnant still on the track reads as unfinished where the identical curve growing forward reads as arrived — and multi-step jumps are instant because a jump is a navigation rather than a progression, so sweeping a front across the crossed segments only makes the user sit out a journey they asked to skip. Where one span is drawn by several segments (the on-track layouts split a span between two steps, three when a content slot sits between them) the segments take abutting slices of the span's time and run linearly, so the fill reads as one line growing at a constant speed rather than pieces lighting in turn.Five visual fixes land with the promotion. Horizontal steps now divide the track evenly instead of sizing to their own labels, so every progress segment is the same width regardless of how long a step is named. Number indicators shrink from 20px to 16px to match the check, ring, and custom-icon indicators, so a step swapping its number for a check as it completes no longer nudges the label beside it. A step description now occupies a 16px box rather than a 24px one — it previously inherited the page's line box instead of applying its own leading, which opened an 8px gap under the label. A step's content slot now starts flush with the label above it at every density: the slot renders outside the density-padded label area, so it was hanging one pad short of it. And a vertical on-track step carrying content keeps its connector unbroken — the content renders below the row that draws the line, so the track used to split open around any step with content (#5201).
New Features
- AspectRatio: emit
ratioas a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass anaspect-ratiorule viaxstyle(including under@media/@containerconditions), and plain-CSS/Tailwind consumers overrideaspect-ratiofrom their own unlayered rules, which beat theastryx-basecascade layer regardless of specificity. The mixed-gallery template's hero now switches 3:1 to 3:2 when the grid stacks with a one-line override on a single element, replacing the duplicated hero markup the fixed inline ratio previously forced (#3883, closes #2798) - CLI:
astryx theme targetslists every component theming target — thedefineThemekey, the class it paints, and the props and states it accepts — for one component or the whole system, with--jsonfor lint and audit scripts.astryx theme --helpnow points at component overrides instead of reading as a build-tool menu. The listing andtheme build's override validation share one enumeration of the component docs, so neither can drift from the components (#5115).
Fixes
- neutral theme: darken the light-mode error red from
#e33f4ato#c9303aso the filledBadge variant="error"label clears WCAG 2.1 AA. White on#e33f4ais 4.14:1 and the badge label is 12px/weight 500, so the 4.5:1 normal-text threshold applies rather than the 3:1 large-text allowance;#c9303agives 5.29:1 while holding the hue (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189). StatusDot and the ProgressBar--color-errorrebinding move with it — both are documented as tracking the badge fill so the dot and its badge read as one status language. Dark mode is untouched (dark text on#ff705d, 6.60:1). Addsscripts/check-badge-contrast.test.mjs, which resolves every theme's badge label/fill pair throughlight-dark(),var()indirection and alpha compositing, and holds all of them to 4.5:1 (#4446). - Unified search and build now include components contributed by integrations, so a component registered through an integration is findable and buildable alongside the built-in set instead of silently missing from both (#5259).
- Table - Grouped page template: wrap the rows in
TableBodyThe template rendered<TableRow>straight into<Table>, so the emitted DOM was<table><tr>.<table>cannot contain a row directly: the HTML parser inserts an implied<tbody>when it parses server-rendered markup and React does not when it renders on the client, so anyone who copied the template into an app as a server-rendered page inherited a hydration mismatch in their own app. Client-only the DOM is still invalid — nothing reparents the rows, so the table ends up with<tr>children and no<tbody>at all, and any CSS or query aimed attbodysilently misses.The rows now sit in<TableBody>, the same element the data-drivendata={...}path renders, so styling, dividers, and column widths are unchanged (#5278).
Other Changes
- Public component theming vars are enumerable, and guarded against being documented but unsettable
collectThemingVarsjoinscollectThemingTargetsas part of the one enumeration the theming surface is read from. Two guards ride on it: a documented public var no component reads compiles to a declaration that never applies, and a var the component writes inline outranks every cascade layer, so no theme can reach it. Both had shipped; neither is visible in the generated theme CSS the jsdom suites assert on (#5409).
Contributors
Thanks to everyone who contributed to this release:
0.4.7
No changes in this release.
0.4.6
New Features
- An integration can contribute reference-doc topics: point
docsat a root inastryx.integration.*and every{topic}.doc.{ts,mjs,js}under it is served byastryx docs, indexed byastryx search, and named in the agent-docs block, beside the built-in topics. A topic may also declarereplaces: '<topic>'to take over an existing one (renaming it leaves the old name resolving as an alias) orextends: '<topic>'to merge onto one section by section. A name that collides without declaring either is aninvalid_docissue rather than a silent override, andvalidate-integrationreports it. (#5311) Also fixes the agent-docs block's topic list, which scanned for\w+and so silently dropped every hyphenated topic —getting-started,cli-integrations,browser-support,styling-librariesandworking-with-aiwere missing from every block ever written, and an agent cannot ask for a topic it was never told about. - Five dashboard page templates:
dashboard-cohort-funnel,dashboard-data,dashboard-executive-summary,dashboard-project-statusanddashboard-service-monitoring. Each is a complete page — layout, realistic sample data, and the component choices that go with the shape of the data — soastryx template <name>gives you something to edit rather than a blank frame (#5245).
Fixes
componentbuilt the import specifier for an integration component by joining the package name and the component name, which assumes every component is exported from a subpath named after itself. Components are commonly grouped behind a single entry point named after the concept, so the suggested import pointed at a subpath the package does not export and did not resolve (#4810). The specifier is now resolved against the owning package'sexportsmap, keyed on the directory the component's doc file sits in, and falls back to the package root when that directory is not an exported subpath. A specifier a doc file states for itself is also no longer overwritten.- The upgrade codemod no longer collapses significant JSX whitespace when it renames an element tag. Renaming
<OldName>next to text and a{expression}(e.g.hello {name} world) previously dropped the adjacent space (hello {name}world); element-tag renames are now spliced into the output so the surrounding JSX is left untouched (#5149). - The XDS-prefix codemod no longer produces a file that will not compile. Dropping the prefix renames
XDSButtontoButton, but if the file already had a local binding calledButtonthe rewrite collided with it and shadowed one of the two. The import is now aliased instead, so both survive and the file still typechecks (#5225).
Contributors
Thanks to everyone who contributed to this release:
0.4.5
No changes in this release.
0.4.4
New Components
- Promote
BottomSheetandBottomSheetSwitcherfrom the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
New Features
astryx template --cdnwrites a working no-build-step CDN starter page (#5068). A CDN starter is a template, so it joins the template family beside--skeletonrather than claiming a top-level command. It is a flag and not the positionalastryx template cdnbecause the positional resolves against everythingdiscoverAll()finds, where acdnid would shadow a discovered template.cdn.template.htmlloads Astryx from jsDelivr and esm.sh with no bundler, no install and no build step, with every CDN URL pinned to the Astryx version you have installed — an unpinned CDN URL resolves to whatever is latest and is cached hard, so a page written today breaks tomorrow without being edited. An existing file is never clobbered;--overwritereplaces it, and--jsonreturns the receipt.The annotations are the things that are load-bearing and silent when missing:?external=react,react-dom(without it esm.sh bundles a second React and every hook throwsCannot read properties of null (reading 'useState')),react/jsx-runtimein the import map (the published bundle imports it; omitting it fails the page withFailed to resolve module specifier), and afont-familyonbody(nothing in the stylesheets sets a document font, soButton— which isfont: inherit— otherwise renders its label in the browser's default serif).Three more lessons came out of building a real app on it. The page now<link>s the theme's webfont from Google Fonts, because the theme names Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in<Theme theme={neutralTheme} mode="system">, so light and dark follow the OS — thedata-astryx-themeattribute alone scopes the stylesheet but cannot switch modes. And#root:emptycarries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup ishtm, with a comment saying it is optional andcreateElementis the dependency-free alternative.A recipe that is only read is a recipe that is only assumed to work, so CI renders it:.github/scripts/cdn-template-smoke-test.mjsscaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.astryx theme buildtakes any number of theme files —astryx theme build themes/*.tscompiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared inengines, so a package manager can enforce it at install instead of the build failing later (#5121).defineTheme:color.accentaccepts a[light, dark]tuple (#2279)ColorScaleConfig.accentnow takes either a single hex or a[light, dark]tuple, matchingTokenValue. With a tuple,expandColorScalederives the light half of every generatedlight-dark()pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of thetokens['--color-accent']workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence betweencolorandtokensfor accent-derived values:tokensentries win token by token, thevar(--color-accent)reference tokens follow a--color-accentoverride at runtime, and the baked--color-on-accentstays derived from thecolor.accentseed.
Fixes
- Bottom Sheet showcase block: the filter checkboxes are interactive again (#5157).
CheckboxInputis fully controlled —valueis required and the input only moves when the owner updates it. The showcase passed a literalvalue={false}with noonChange, so the three filters ("In stock", "On sale", "Free shipping") rendered but could never be toggled: on the docs site the first thing a reader tries in a Bottom Sheet does nothing, and anyone copying the block inherits three dead controls. Each filter now has its ownuseStateandonChange, matching the checkbox wiring already used in the Bottom Sheet Switcher showcase. - An integration whose manifest fails to load is no longer silent. A manifest that throws on import — the common case being one still calling a
create*authoring factory, removed in 0.3.0 — contributes nothing, and the CLI treated that as if the package had never been configured:astryx discoveransweredNo integrations configured.whileastryx.config.mjsplainly configured one, and no command said a word. The only way to find out was to already suspect it and runvalidate-integrationby name. A configured integration could remain invisible to CLI discovery, leading an app team to conclude that its components did not exist (#5119). The load error now counts as an integration issue, so the existing one-line stderr nudge fires oncomponent,templateandupgrade, anddiscover— the command whose whole job is listing integrations — nudges too, as doessearch.discoveralso stops reportingconfigured: falsefor a project that configured an integration that failed to load; the empty state now distinguishes "you configured nothing" from "what you configured contributed nothing", which is the distinctionmeta.configuredwas introduced to carry.Nothing becomes fatal: the warning is best-effort, stderr-only, suppressed under--json, and never changes an exit code. Broken contributions are still skipped exactly as before.
Contributors
Thanks to everyone who contributed to this release: