What's New

Release notes and changelog for all packages.

0.5.1

New Features
  • Component docs can declare structured usage.accessibility requirements, and astryx component renders them as a dedicated Accessibility section in full and compact output. Translated and dense documentation overlays preserve the base accessibility guidance unless they explicitly replace it. (#5646)
  • Icon APIs and themes accept namespaced extension keys, and NumberInput steppers use numberInput:stepperDown without widening the required IconRegistry keys (#5466) <Icon icon>, useIcon, and defineTheme({icons}) accept keys such as numberInput:stepperDown and richtext:bold; misspelled built-in names remain type errors. NumberInput keeps a compact centered Core fallback, while themes can override its steppers independently from the shared chevronDown semantic.
  • Rebuild the settings-dialog page template with searchable navigation, responsive grouped controls, live appearance previews, configurable keyboard shortcuts, and docsite gallery visibility. (#5568)
  • New table-filter page template: a table page built around a filter token list (#5448) Ports the feature set of the internal XDS table page pattern onto Astryx primitives. The filter row is a token list of quick-filter toggles and field controls — Selector, MultiSelector, and a ComplexSelector wrapping a range Slider — that swaps to PowerSearch for anything the tokens can't express. Both modes read and write the same PowerSearchFilter[], so a filter built in either survives the swap. Controls carry field chrome when unset and a pressed fill once they hold a value, so the row reads as one family whether a clause came from a toggle or a selector.
    Around that: saved views that capture the filters and the whole table configuration, a bulk-edit bar that slides in on selection, and a view options popover with four panels — a drag-and-drop column transfer list, density, sticky edges, and grouping — that apply instantly. Clicking a row opens a resizable detail panel. The list pages in by infinite scroll against an IntersectionObserver, with skeleton rows aligned to the table's own column grid standing in for the batch in flight, and empty states for the no-results and no-data paths. The toolbar wraps to a second row under a container query rather than a viewport one, so it responds to the width the detail panel leaves it.
    Uses the Table - Filtering category, already reserved in the TemplateCategory union.
Fixes
  • build/search no longer rank a partially-matched template above one matching every term, no longer index TypeScript generic arguments as rendered components, and no longer treat breadth of rendered components as full-strength relevance. (#5614)
  • Component and hook names resolve case-exactly on macOS and Windows, matching Linux (#5478) findComponentReadme, findComponentSource and findHookDoc probed candidate paths with fs.existsSync, which answers through the filesystem's own case folding. On a case-insensitive filesystem astryx component button resolved to Button instead of reporting an unknown component with suggestions, and findHookDoc(core, 'mediaquery') returned .../hooks/useMediaquery.doc.mjs — a spelling that exists nowhere, and that breaks any consumer reading it on Linux. The probes now verify each path segment against its parent's real directory listing, so these component and hook lookups resolve the same names to the same real paths on every host. The deliberate case-insensitive hook lookup is unchanged; it now returns the file's true casing.
  • The 56 --color-data-* defaults now reach runtime CSS and built themes from the same source, while dashboard template fallbacks match those defaults (#5562, #5566) The defaults live once at :root in @layer astryx-base, so nested themes inherit parent overrides and astryx theme build matches <Theme> while generateThemeCSS keeps its existing return shape.
    Visual change. A chart or template that previously painted nothing or used a mismatched hex fallback now paints the data token's default. Pin an explicit color to preserve a previous fallback.
  • The theme-showcase page no longer clips its own controls. In the store's product cards the quantity field and "Add to cart" button spilled out of both sides of the card; in the checkout card the card number truncated mid-number (1234 1234 12), the country selector ellipsized, and the pay button was left with only a few pixels of slack. (#5539) The product-card row is the more visible of the two. It had no width of its own — the enclosing stack centers rather than stretches its children — so it sized to its contents and, being centered, overflowed the card at both edges once those contents outgrew it. That stayed hidden while the quantity field was narrow, and surfaced when NumberInput moved to type="text" for formatted display: a text input's default size=20 made the field ~200px instead of ~65px, and the template was pinning it with a style minWidth (a floor, not a cap) plus flexShrink: 0. The field now uses NumberInput's width prop, which is what actually sizes a field, and the row is pinned to the card width and allowed to wrap so the button drops to its own full-width line instead of ellipsizing on a narrow card.
    The checkout sat in a grid track with a 200px minimum, so its width was a fraction of however many tracks happened to fit — it swung between 208px and 328px as the viewport resized, and the narrow end is well under what the form needs. Themes with a large spacing scale suffered most: Matcha's --spacing-5 card padding alone spends 60px of that budget.
    The checkout and chat panels are now a wrapping flex row. They share a row at roughly 1:2 while both flex bases fit, then the chat drops to its own full-width row, which makes 300px a floor for the checkout rather than an accident of the track count. Raising the track minimum instead would have left a tall gap beside the checkout at mid widths, since a two-track row can't hold a two-track span.
    Two narrower fixes ride along, both text the card was breaking rather than fitting: the payment-method grid's minimum goes 70px to 80px so "Google" stops breaking mid-word on Matcha and Y2K, and on phones the card drops one padding step and sheds the card number's decorative start icon, which together buy back the room a 16-digit number needs at 360px.
Documentation
  • useAnnounce, useTypeahead, useInteractiveRole, useLongPress, useInputStatusIcon, useDevWarning and useIndicatorFocusRing are now discoverable. The CLI's hook index is built from the .doc.mjs files next to each hook, and these seven shipped without one; so astryx hook <name> answered "No hook named", astryx hook omitted them and astryx search never returned them, while the package exported them with full TSDoc. Agents following the documented discovery workflow concluded the primitives did not exist and hand-rolled replacements; for useAnnounce that means a hand-built aria-live region, which usually does not announce at all. A test now fails when a hook is exported from the barrel without a doc, so the index cannot silently go stale again. (#5109)
  • rewrite all 46 page template descriptions to describe layout, container, data shape and behaviour — the things that actually differentiate one template from its siblings — instead of the sample data they happen to ship with, so build and search retrieve them from a description of the problem rather than a guess at the slug. (#5615)
Contributors
Thanks to everyone who contributed to this release:

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.