What's New

Release notes and changelog for all packages.

0.5.0

Breaking Changes
  • Banner: the collapse axis moves onto one collapsible prop, and content can opt out of collapsing (#5255) Banner inferred its disclosure from its content: any children got 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 — and defaultIsExpanded was the only knob, with no controlled mode.
    The whole axis is now one boolean | CollapsibleConfig prop, following the boolean-or-config convention SideNav.collapsible set, and backed by the shared useCollapsible hook 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: controlled
    The default is unchanged — a banner that never mentioned defaultIsExpanded behaves exactly as it did. The breaking part is the prop itself: defaultIsExpanded is 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-content
    It rewrites defaultIsExpanded to collapsible={{defaultIsOpen: true}} and drops defaultIsExpanded={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. defaultIsExpanded inside 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 for defaultIsExpanded after running the codemod and migrate any spread sites by hand.
New Components
  • Promote Stepper and Step from 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 default aria-label is 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 under prefers-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 ratio as a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass an aspect-ratio rule via xstyle (including under @media/@container conditions), and plain-CSS/Tailwind consumers override aspect-ratio from their own unlayered rules, which beat the astryx-base cascade 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 targets lists every component theming target — the defineTheme key, the class it paints, and the props and states it accepts — for one component or the whole system, with --json for lint and audit scripts. astryx theme --help now points at component overrides instead of reading as a build-tool menu. The listing and theme 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 #e33f4a to #c9303a so the filled Badge variant="error" label clears WCAG 2.1 AA. White on #e33f4a is 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; #c9303a gives 5.29:1 while holding the hue (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189). StatusDot and the ProgressBar --color-error rebinding 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). Adds scripts/check-badge-contrast.test.mjs, which resolves every theme's badge label/fill pair through light-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 TableBody The 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 at tbody silently misses.
    The rows now sit in <TableBody>, the same element the data-driven data={...} 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 collectThemingVars joins collectThemingTargets as 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 docs at a root in astryx.integration.* and every {topic}.doc.{ts,mjs,js} under it is served by astryx docs, indexed by astryx search, and named in the agent-docs block, beside the built-in topics. A topic may also declare replaces: '<topic>' to take over an existing one (renaming it leaves the old name resolving as an alias) or extends: '<topic>' to merge onto one section by section. A name that collides without declaring either is an invalid_doc issue rather than a silent override, and validate-integration reports 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-libraries and working-with-ai were 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-status and dashboard-service-monitoring. Each is a complete page — layout, realistic sample data, and the component choices that go with the shape of the data — so astryx template <name> gives you something to edit rather than a blank frame (#5245).
Fixes
  • component built 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's exports map, 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 XDSButton to Button, but if the file already had a local binding called Button the 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 BottomSheet and BottomSheetSwitcher from the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
New Features
  • astryx template --cdn writes a working no-build-step CDN starter page (#5068). A CDN starter is a template, so it joins the template family beside --skeleton rather than claiming a top-level command. It is a flag and not the positional astryx template cdn because the positional resolves against everything discoverAll() finds, where a cdn id would shadow a discovered template. cdn.template.html loads 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; --overwrite replaces it, and --json returns 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 throws Cannot read properties of null (reading 'useState')), react/jsx-runtime in the import map (the published bundle imports it; omitting it fails the page with Failed to resolve module specifier), and a font-family on body (nothing in the stylesheets sets a document font, so Button — which is font: 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 — the data-astryx-theme attribute alone scopes the stylesheet but cannot switch modes. And #root:empty carries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup is htm, with a comment saying it is optional and createElement is 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.mjs scaffolds 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 build takes any number of theme files — astryx theme build themes/*.ts compiles 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 in engines, so a package manager can enforce it at install instead of the build failing later (#5121).
  • defineTheme: color.accent accepts a [light, dark] tuple (#2279) ColorScaleConfig.accent now takes either a single hex or a [light, dark] tuple, matching TokenValue. With a tuple, expandColorScale derives the light half of every generated light-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 the tokens['--color-accent'] workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence between color and tokens for accent-derived values: tokens entries win token by token, the var(--color-accent) reference tokens follow a --color-accent override at runtime, and the baked --color-on-accent stays derived from the color.accent seed.
Fixes
  • Bottom Sheet showcase block: the filter checkboxes are interactive again (#5157). CheckboxInput is fully controlled — value is required and the input only moves when the owner updates it. The showcase passed a literal value={false} with no onChange, 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 own useState and onChange, 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 discover answered No integrations configured. while astryx.config.mjs plainly configured one, and no command said a word. The only way to find out was to already suspect it and run validate-integration by 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 on component, template and upgrade, and discover — the command whose whole job is listing integrations — nudges too, as does search. discover also stops reporting configured: false for 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 distinction meta.configured was 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: