What's New

Release notes and changelog for all packages.

0.7.12

Experimental APIs
  • discover lists the Lab ChatVirtualizer among the official @astryxdesign/lab components. (#5461)
  • astryx discover lists the experimental TabBar and TabBarItem components from @astryxdesign/lab. (#9700)
  • integration check and experimental icon new-set follow export const X = Y to where Y is declared: an icon-set theme map or icon export written that way is now checked and recorded. (#10471)
  • Icon sets: when a wrapped library ships no license file, integration check on an icon set, experimental icon new-set --from, and a refresh name the NOTICE file to add and where, and the icon-sets guide lists the file names that count. A refresh from a library root moves icons added one file at a time from that library to the root import, keeping their ids, exports, map entries, variants, and words, and the receipt lists them under moved. Each keeps that id and export on every later refresh, and refreshing again changes nothing. A refresh keeps an id you chose that is not a spelling of the library name (dismiss for XIcon), also for an icon that already reads the root; it renames only an id the current rule spells differently. A library icon whose id or name a moved icon already has is left out. An icon whose root export another icon of the set already reads stays on its own import, and the receipt says why. A variant from another file of the package, such as a solid look, stays on its own import, and every export the refresh does not write again stays in the generated module. A LICENSE directory counts as a license notice in neither the receipt nor the check. (#10458)
  • Icon sets: wrapping a large icon library that names its looks in its exports works in seconds and gives one icon per glyph. Only the experimental icon commands, the icon-set guide, and integration check on an icon set change. (#8013)
    • Large libraries. experimental icon new-set --from reads a library of 20,000 exports in about ten seconds instead of minutes, and in text mode says on stderr that it is reading and what it found. iconNewSet and iconAdd report reading progress for large modules through the shared logger (stderr, text mode only); called directly, they stay silent until logger.setSilent(false).
    • Libraries of looks. A library whose export names end in style, size and weight words (XOutline24WGHT500Icon), never direction words like Up and Down, gives one icon per glyph, named x (XIcon), in the look the set's default variant names, else the library's usual default; suggestions and add name icons by glyph, add --variant filled --all picks each glyph's filled look, a refresh keeps every icon an earlier release wrapped, and a refresh with a new --default-variant moves each glyph to that look. Every command that records the default variant takes it from the look each icon's export draws, refuses a look word the library does not have, and never adds a second export of an icon.
    • Variants on an existing set. experimental icon new-set <set> --variants outline,filled without --from declares variants (a set with icons keeps its default variant, or, with none declared, takes the look its icons draw; a set whose library's export names name no looks keeps it on a refresh too, refuses --variants that leave it out, and the refusal names the add --variant run that adds the other look), and --display-name and --description rewrite the descriptor, in place; add --variant names an undeclared variant with that command.
    • Commands that run as printed. Every command new-set, add and map print names the set, with --set where the command takes it; the commands add lists repeat --default and --id; --new-definition and new-definition take kebab-case as the definitions list shows it, and an unknown --definition suggests a name the next command takes.
    • Search. experimental icon star no longer offers start, a plural matches its singular, go home finds the icon mapped to home, and a letter or two never matches inside a word.
    • Checks. A set's own definitions pass integration check --strict, and the generated module and its declaration file pass after a formatter rewrites them.
    • Theme icons. Each themeIcons entry is sized to its box by CSS, so a component that writes its own size attributes still fills the theme's icon box.
  • astryx experimental render matches compilerOptions.paths keys and targets by TypeScript's rules, from the project's own tsconfig.json or jsconfig.json (a config it extends is not read). Newly, a * may sit anywhere in a key or a target ("theme-*-x", "./icons/icon-*"), and a key's targets are tried in order, so a module, stylesheet, image or JSON file under a later target is found; --reverse puts a file back under the target its sent path names (the one whose folders match the most of the path above the file, a target with text before its * included), else under the first target. Only bare specifiers are matched, an import whose targets do not exist resolves as a package, and a catch-all "*" key never turns a missing package into a path error. A module the page loads from outside its own files and outside node_modules (a sibling package's source, say) resolves a bare import through the same aliases first, as the page's own files and TypeScript do, so the page and that module load one copy of a package; an import no alias places resolves as a package, so an installed package that a prefix key also names ("@scope/*" and @scope/realpkg) still loads. --reverse of a rendered file that lost its embedded source on the way (and has no Astryx components to rebuild from) now fails with ERR_RENDER_SOURCE_DAMAGED, saying so, instead of ERR_RENDER_NOT_ASTRYX. (#8012)
  • Icon sets: an icon whose name would start with a digit once the library prefix comes off, such as a library's fa0, now keeps that prefix: it gets id fa-0 and is exported as Fa0Icon (fa500px becomes Fa500pxIcon). The CLI wrote 0Icon before, which is not a valid JavaScript name, so the generated module did not parse. An id you give that starts with a digit, with no prefix to keep, is refused with a message that asks for an id that starts with a letter. Only experimental icon new-set --from and experimental icon add change; a set they write now passes integration check. (#10895)
  • Icon sets: experimental icon add --variant <look> --from <module> --all now works for a library that ships each look as its own package, such as Font Awesome's solid and regular packages of icon data objects. Before, it found no icon to give the variant, because every icon came from another package. An icon gains the variant from the export of the same name and kind, and the receipt lists as missing the icons of that library that the look's package does not export. Wrapping such a library also no longer turns a pack export (fas, an object of the other exports) into an icon, so the shared fa prefix comes off the names again. A name that would then start with a digit keeps the prefix (fa0 becomes Fa0Icon), so the generated module still parses. Only the experimental icon commands and integration check on an icon set change. (#10896)
  • Icon sets: after you rename an icon-set package in package.json, the next experimental icon command that writes the data file (new-set on the existing set, with or without --from, add, map, or new-definition --icon, even one that changes nothing else) writes the new package name to the data file's module, and keeps any subpath (@acme/old-icons/outline becomes @acme/new-icons/outline). Before, the old name stayed, and integration check failed until you edited the file by hand. The receipt of each of these commands names the new and the old module (Updated module to "@acme/new-icons/outline" (was "@acme/old-icons/outline"), from the package name in package.json.), and map words each map entry from what it replaced, so an entry that did not change says so. Only the experimental icon commands and the icon-sets guide change. (#10897)
  • astryx experimental render draws recharts charts. A recharts chart draws only after its effects run, and a ResponsiveContainer measures its parent in a browser, so a rendered page showed an empty box for every chart. The render now draws each chart and ResponsiveContainer a page imports from recharts by name, after the server render, in a small document with no layout. A container starts at its own width and height, or at a width that follows its height, and the drawing scales to the width the page gives it. The chart-size warning counts the charts the render could not draw, and says when charts were drawn by themselves (when the page cannot be drawn again without a browser, or its effects change its charts or re-render the component that makes them). Charts show the data and props of the page's first render; a value a chart's parts read from a React context that an effect changes may show its later value. (#10382)
  • exportSearchIndex() and rankSearchIndex() from @astryxdesign/cli/api store and rank search's candidates. exportSearchIndex({cwd, package}) returns {version, candidates}: what search() ranks in a folder, as plain JSON (with package, only that package's entries). rankSearchIndex(query, indexes, {type, limit}) ranks stored indexes with search's own tree: an index made in a project answers as search(query) does there, with the same response; for an index made outside a project, theme results name theme add where search there names theme eject. A catalog that lists packages it must not load makes the index where loading is safe and ranks it per query. An index is ranked only by the CLI version that made it. Both are experimental (they may change in a patch release), and their docs are not search results, so search and build answer exactly as before. When they are promoted to stable, their docs join search. (#10375)
New Features
  • astryx discover lists the Lab DialogHeroHeaderShowcase template from @astryxdesign/lab. (#10109)
  • astryx discover lists the Lab DialogHeroHeader component from @astryxdesign/lab. (#10108)
  • BottomSheet: at rest, a sheet's content starts below the grab bar whatever its padding, so the first line is no longer drawn through the bar's fade. The block-start inset is never less than the bar's height (--spacing-6): the band under the bar is not padding a child escapes, so a lone Section starts below the bar too; scrolled content still passes beneath it. A sheet at the default padding starts its content 8 px lower, one with padding={0} starts it below the bar, and one whose only child is a Section starts that Section 24 px lower and grows by the same amount. Core's own padding={0} sheets (the touch date and time pickers, the DropdownMenu and ContextMenu sheets, and the PowerSearch and Tokenizer sheets) no longer reserve that band themselves, so the pickers, PowerSearch and Tokenizer look the same and a menu's first row sits 8 px lower. The CLI's table-filter and table-inbox page templates drop their own band too, so it is not doubled. (#8558)
  • ChatLayout keeps its composer on top of the software keyboard where the visual viewport shrinks for it, instead of leaving it underneath until the browser scrolls the whole page. In Chrome on Android the dock rides Gboard's measured slides up and down, in step with the keyboard. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. Where a page sets interactive-widget=resizes-content, Chrome shrinks the page for the keyboard itself and the composer stays above it without moving. A conversation at its newest message stays there, and the rest of the transcript can still be scrolled above the composer. On a touch screen, in a top-level page, every way into the composer's text (a tap, the keyboard's previous and next buttons, Tab, the input's focus()) reaches it without the page scrolling; under a mouse or inside an iframe the browser's own focus applies. In a top-level page on a touch screen, the composer's wrapper (without the scroll-to-bottom button) is a group with no name. When the keyboard's Done ends typing, focus rests there (it is no tab stop), so the next tap or Tab starts from the composer; it shows the focus ring after keyboard input only. A tap that focuses the composer still raises its click once. Under a mouse or inside an iframe, the wrapper is a plain container. Under Reduce Motion the composer never travels with Gboard: it cross-fades to its place above the keyboard. Under a mouse, with no software keyboard, nothing changes. The browser-support guide's section on the on-screen keyboard covers ChatLayout's composer. (#8176)
  • astryx lists a create… factory documented as a hook, such as createReorderable, with the hooks. (#8139)
  • astryx docs also opens a docs-tree node by its bare name, or by a route that drops the prefix its name repeats, when exactly one node matches: astryx docs tokens-color and astryx docs tokens/color both open tokens/tokens-color. Two or more nodes answering one name still fail with the suggestions they always listed, and an experimental doc still opens only by its marked route. (#10387)
  • astryx docs --depth <levels> now names the docs below each namespace on the topic list, by the route that opens them, so one read learns every route instead of one read per namespace. Without --depth the list is unchanged, and the JSON keeps its shape: the new children sit inside each meta.namespaces entry. (#10393)
  • The official-packages discovery list now includes the Lab LineClamp component, so astryx can find and describe it. (#4259)
  • Tables can window fixed-height flat data: pass useTableRowsVirtualization({rowHeight, initialViewportHeight}) to Table.virtualization. Table keeps the complete data and row identity, mounts only the rows in its viewport plus a few overscan rows, keeps native table semantics with full-table row positions, keeps the focused row mounted, and falls back to rendering every row for content or geometry it cannot window. Tables that do not opt in are unchanged. (#8280)
  • Table plugins can now read where a row sits. Table passes each body row and cell transform an immutable TableRowContext (the row's key, its zero-based logicalIndex in the complete data, the row and header counts, and the row model). It passes the scroll-wrapper transform a TableRenderContext with a stable viewport reference. A plugin declares rowModel: 'flat' when its body transforms keep one row per data item. useTableSelection and useTableStickyColumns declare it. useTableRowIndex() without options now numbers rows from the context (passing data still numbers from that array), and rows that move re-render only for plugins that read the index. Read context values during the transform; a later read from a callback warns in development. The CLI's numbered-rows block no longer passes data. (#10171)
  • Replace the theme showcase's custom layout, text and icon styling with Astryx components. The embedded preview paints the theme's body behind card-token surfaces instead of a surface-colored card band. The new standalone top-navigation shell uses the theme's surface canvas; the embedded view stays shell-free. Make demo inputs, cart feedback, inventory filters and chat respond locally, with clearable filters and no payment submission. Keep the template id, gallery visibility and demo content. (#10404)
Fixes
  • On Android, text follows the reader's system font scale in every theme with no setup, in browsers that report env(preferred-text-scale) (verified on Chromium and on Chrome stable). The root Theme reads env(preferred-text-scale) and scales every font size by it, as it already follows Dynamic Type on iPhone. Before, the system font scale reached Astryx text only when the page added <meta name="text-scale" content="scale">. A page with content="scale" keeps working as it did: its root font size carries the scale, and the root Theme adds none. Browsers without either see no change. astryx docs typography/type-scale describes it. (#10727)
  • Comments, a codemod note and the grouped-table template's sample data no longer use internal-format identifiers. (#10958)
  • astryx swizzle --list no longer lists Core's shared folders (animator, gestures, i18n, internal, keyboard, motion, privateAttributes, __tests__) as components. A copy of gestures imports @astryxdesign/core/motion, which the core package does not export. (#10185)
  • astryx component prints a theme warning as one line: control and format characters in the configured astryx.theme value or the generated theme record print as �, so a newline or an escape sequence in a checkout cannot rewrite the terminal. (#10764)
  • astryx docs <topic> reads a topic authored as .doc.ts from an installed integration on every supported Node, and from a linked integration below Node 22.18. Topic and docs-tree files now load .ts through the same TypeScript loader as component docs, where a plain import failed under node_modules ("Stripping types is currently unsupported") and below Node 22.18 ("Unknown file extension .ts"). astryx search also reads an installed .doc.ts component doc, so it finds the component by its keywords, shows its description, and lists a family's members. .doc.mjs topics load as before. (#10763)
  • A long-running process that calls the CLI's API, such as a docs site's search route, now reads an edited CommonJS .doc.js file again in docs, search and template reads. It read the doc as first loaded. (#10760)
  • A command that reads a project module again after changing it, such as astryx integration add checking the manifest it just wrote, now reads the change for an ES module .js file in a package without a "type" field. It read the module as first loaded. (#10745)
  • Gothic: accent text and accent icons stay readable on a light media surface. They used Gothic's light accent there, near-white on a light band (1.14:1); now they follow the surface's dark accent (18.7:1 against a white surface). The CLI's Gothic theme template carries the same change. (#10852)
  • Icon sets: integration check now accepts a generated declaration file (*.generated.d.ts) whose long type arguments a formatter such as Prettier re-wrapped. Before, the re-wrapped line made the check report icon_generated_types_mismatch and fail. A changed declaration still fails the check. The experimental icon commands are unchanged. (#10898)
  • Neutral: an unselected SegmentedControl label meets 4.5:1 in dark mode on AppShell's surface. The track is translucent, so it lightens the surface under the label: [#9](https://github.com/meta/astryx/pull/9)e9e9e on [#3](https://github.com/meta/astryx/pull/3)c3c3c measured 4.11:1. The label now takes neutral.dark[80] (6.46:1), the same lift Neutral already gives secondary text on its selected rows and pills. Light mode is unchanged, and the CLI's Neutral theme template matches. (#10881)
  • astryx build: when an idea names a family only after its head ("a saml for a login") and the family's base template matches no other word, the variant that outranks the base now stays the start (login-sso, not login), so adding page templates no longer flips such ideas to the base. Ideas that name the family in their head ("saml login") start as before. (#10431)
  • astryx experimental render no longer dies silently with exit 139 when Node itself crashes while it renders a page. The page now renders in a separate process, so a crash (a crash signal, or a crash status on Windows) ends only that process, and the render fails with ERR_RENDER_FAILED and a message that names the Node version and path; a signal that stops it names them too. That process ends when the CLI ends, so a page that never finishes does not outlive a stopped CLI. Some Node builds crash in Intl.Segmenter, which components such as Avatar use to split text: on such a build the render runs the page once more without Intl.Segmenter and adds a node-crash warning that names the Node build and says the output may differ slightly (a joined emoji, a flag, or a letter with a separate accent mark in initials), so pages with Avatar render again. (#10915)
  • astryx search puts the results that fit the whole query higher. The first result stays the same. At the default limit, and at any limit of 10 or more, the set of results stays the same. A smaller --limit shows the top of the new order, so it can show a different result. Below the first result, inside each group of equally strong matches, a result whose docs fit the query much worse than the others in its group moves after them. A result whose name spells two or more of the query's words never moves down; it can still move up. The fit uses the same word-meaning weights astryx build uses to pick blocks, so a new component or template is placed from its own docs. A query that is an entry's whole name keeps its answer. (#10926)
  • Every import in an astryx swizzle copy now names a file the copy holds or a path the owner package exports. Before, the copy sent every import that left the component folder to the package's folder entry, which does not export the internal helpers most components use, so Button, Dialog, Table and about 100 other copies failed to type-check or bundle. Now the copy imports what the package exports from the package, carries every internal module it needs beside it in the package's folder layout, and copies the nested folders it imports (such as Table's plugins/). Test helpers and notes are no longer copied. A helper an earlier swizzle wrote is reused when it is the same and is never replaced by a copy that carries it, even with --overwrite: a different one stays, and the new copy writes its own under a version-suffixed name. Swizzling the component whose folder holds that helper treats it as one of that component's own files, which --overwrite replaces. A private attribute owner module and the style modules it imports are the exception, as before: a changed copy fails the command without --overwrite and is replaced with it. Fixes #3506. (#10197)
  • A swizzled component whose source imports another Astryx package's internal module, such as a Lab component that uses Core's gesture primitives, no longer imports that private path, except a StyleX module that package exports, which the copy keeps importing by that path because its identity is its path. Swizzle carries every other such module, and what it reaches, into the copy under a folder named after its package (for example components/astryx/core/internal/touch.ts); that package's public names are still imported from the package. (#10595)
  • astryx swizzle reports the npm packages a copy imports, such as d3-scale for a chart, with the version range the owner package declares, so the copy builds once you install them. The swizzle.copy receipt lists them in dependencies, and the text output names them to install. Node's built-in modules and the owner package itself are not listed. (#10502)
  • astryx swizzle writes an astryx-swizzle.json marker into an output folder it owns (one the copy creates, an empty one, or one it marked before), naming each package the folder's copies came from and its version. @astryxdesign/build's Babel, PostCSS and Vite integrations, and withAstryx() under webpack, compile the copies under that folder below astryx-theme, so a theme's component overrides reach a swizzled component as they reach the package component. For a folder that already holds other files it writes no marker and says what it found and how to add the marker by hand; the swizzle.copy receipt reports this in a new optional marker field. Under Turbopack and with the stock StyleX plugins, a copy's styles still land above the theme. The marker is not listed among the copy's files. (#10483)
  • The table-filter template's link-style header actions set minHeight: 0 with their auto height, so no minimum holds them taller than their text. (#10588)
  • astryx template <name> puts the template a typo slips from first in its suggestions: a name one or two slips away (a letter added, dropped or changed, or two letters swapped, as in AppShellCotnentOnly or dasbhoard) ranks just below the templates that carry every typed word. The suggestion list is never longer than before. (#10712)
  • In Safari on iPhone, text follows the reader's text size (Dynamic Type) in every theme, branded included. Where the browser exposes that size through font: -apple-system-body, as Safari on iPhone does, the theme's font sizes scale with the size the reader picked in Settings (Display & Text Size, then Larger Text), each size on the curve of the iOS text style it plays: body text like Body, heading-1 like Title 1, display text like Large Title, with every role kept in order. A semantic size a theme fixes at a length, such as the 0.75rem supporting text of Butter, Stone and Y2K, scales on the curve of the step it reads by default. At the default size every font size is the theme's own; the family, spacing, line-height ratios and the root font size never change, text inputs keep their 16px floor on iOS, and browsers without the keyword see no change. There is no option, prop or document attribute: the root Theme reads the reader's size from a hidden element. astryx docs typography/type-scale describes it. (#10416)
  • Matcha: light-mode secondary text is slightly darker (Neutral Light 30), so it meets 4.5:1 on the body (5.11:1, was 3.83:1), the surface and the card. (#10932) [fix] Y2K: light-mode secondary text is slightly darker (Neutral Light 35), so it meets 4.5:1 on the Periwinkle body (5.14:1, was 4.25:1). The CLI's Matcha and Y2K theme templates match.
  • The Butter, Stone and Y2K themes set supporting text (--text-supporting-size) in rem instead of a fixed 12px, so it grows when a reader raises the browser's default font size, like the rest of the text. At the default size it is still 12px. The CLI's copies of these themes match. (#10320)
Documentation
  • A new Course Detail page template: a long-form sales page for a single offering in two columns — the long read (a preview poster with a fact row, an about block with skill chips, a module syllabus whose sections collapse module by module, an instructor card, reviews with a scored-aspects panel, and a FAQ) beside a sticky enroll rail (the price with a compare-at, a self-paced or cohort start picker, and a weekly-pace slider that computes a finish date). Copy it with astryx template course-detail <path>. (#9753)
  • The File Explorer page template scrolls its columns with StackItem and HStack isScrollable instead of custom overflow and flex styles, and names each column after the folder it lists while the column scrolls. Its chevrons now mirror in right-to-left, and a detail pane scrolled to its end keeps its bottom padding. (#10421)
  • Hook docs for useCalendarConstraints, so astryx hook useCalendarConstraints and astryx search return it, and a useCalendarConstraints — Hotel Booking Range example block: a booking range picker that enforces min/max dates, disables closed Mondays, and caps reservations at 7 nights once check-in is selected. Copy it with astryx template useCalendarConstraintsHookUsage <path>. (#10151)
  • Hook docs for useCalendarNavigation, so astryx hook useCalendarNavigation and astryx search return it, and a useCalendarNavigation — Month Pager example block: a month-by-month calendar with Previous/Next controls, localized month-year header, and cross-month arrow key navigation using pendingFocus. Copy it with astryx template useCalendarNavigationHookUsage <path>. (#10154)
  • Hook docs for useLinkify, so astryx hook useLinkify and astryx search return it, and a useLinkify — Links in a Comment Thread example block: plain-text comments where the URL and email become Links and a custom [#123](https://github.com/meta/astryx/pull/123) issue-reference pattern shows the patterns option, while a comment without matches stays plain. (#9969)
  • Add usePowerSearchConfig hook docs and a filtered directory table example block (#10660)
  • Add useTableColumnSettingsState hook docs and a column visibility picker example block (#10652)
  • A useInteractiveRole — One Tile, Four Roles example block for the existing hook docs: a polymorphic Tile rendered four ways — href link, onClick button, Popover-trigger context button, inert content — showing the resolution order in one place. (#9972)
  • Fix the useStreamingText — Streaming Response example block: it passed isStreaming as false, so the streaming reveal it exists to show never ran. The block is now a chat-style reply card with a Regenerate button that streams the response in bursts — the hook reveals it steadily while streaming and snaps to the full text when it ends. (#9975)
  • RichTextView, RichTextEditorToolbar and RichTextEditorAutoLinkPlugin each ship a doc file, so astryx component, astryx discover and the docs list their props, defaults and usage. (#10407)
  • Tab's docs show how to give a tab help text: anchor a Tooltip on the Tab through its ref, so the description lands on the tab, and put a decorative info Icon in endContent. endContent is documented as non-interactive: a button, link, or InfoTip inside it would nest a control inside the tab's button. (#10734)
  • The grouped table page template groups its rows with useTableGroupedRows instead of hand-rendered header rows and a hand-written colgroup. Its columns now have headers, each group's toggle is a button that reports whether its group is expanded, and the row menu's Move to project arrow mirrors in right-to-left. (#10423)
  • The Tailwind guide (astryx docs styling-libraries/tailwind) adds a recipe for an app that already uses Tailwind: keep the app's own @import "tailwindcss", put the @layer line above it, and add the Astryx stylesheets after it. It explains why the @layer line must come before the Tailwind import: below it, the Astryx reset outranks every utility class, and nothing reports it. The Core README's Next.js + Tailwind section points to it. (#10532)
  • The useInputStatusIcon — Coupon Code Status example block's field applies inputWrapperStyles.textField. A field copied from it now shows its focus look at once when the primary pointer is coarse, as Core's text fields do. (#10649)
Other Changes
  • Internal: doctor.mjs and template.mjs are formatted with Prettier. No change to any command's output. (#10988)
  • Internal: the icon-set export reader reuses the shared top-level helper, and a source comment on look refreshes is shorter. No change to any command's output. (#10449)
  • Internal: the doc importers import each doc file through one small module that the CLI's own test project loads natively, so its tests no longer time out on a busy machine. No change to any command's output. (#10740)
Contributors
Thanks to everyone who contributed to this release:

0.7.11

New Features
  • astryx build ranks Core blocks of component families its picker was not fitted with somewhat better: the block picker's doc-side word weights are refitted from paraphrases of each block's own source. (#10355)
Fixes
  • astryx build names its two alternative page templates in the same order it chooses the start from, so the three templates it shows for a whole page are its best three. The start, the number of alternatives, the blocks and the JSON shape are unchanged. (#10357)
  • astryx build --type doc and --type theme now point to astryx search <query> --type doc or --type theme: a build kit has no docs or themes, so build says so once on stderr and names the search that finds them. Stdout, JSON output and exit codes are unchanged. (#10401)
  • astryx doctor no longer warns that no theme is wired in an app that imports its themes itself. Without a generated theme module or a package.json astryx.theme, the themes check now passes when the source of the app imports a theme's built module or stylesheet (the imports theme add writes) or passes a theme to Theme, followed through module-scope variables, defineTheme({extends}), re-exports and installed packages to its package, and names the file. Only a theme whose package is installed, or a local theme, counts. A theme passed to Theme that doctor cannot trace (a prop, a function result, a variable declared inside a component) is reported as not confirmed (info), not as missing. (#10353)
  • The CLI's semver range check reads ^0 as any 0.x.y and ^0.0 as any 0.0.y, and reads a hyphen range (1.0.0 - 2.0.0) as inclusive bounds, with a partial upper bound (1.0.0 - 2) covering its whole series as npm does. Before, ^0 and ^0.0 were locked to a single patch version and a hyphen range could never match, so astryx doctor and the peer-version checks reported a false mismatch for projects that declare those ranges. (#10184)
  • The reminder to run astryx init in a project that has not run it no longer prints before every command. It now prints after a command that succeeds, at most once a day per project, recorded in the per-user state as the daily hints are. It does not print with --json, after a command that fails, or when CI is set. astryx doctor still reports the missing setup in its agent-docs check every time. No JSON shape or exit code changes. (#10343)
  • In a folder inside an Astryx project whose own package.json declares no Astryx package, such as a tool folder that installs its own @astryxdesign/core, the setup reminder's init command now names the project's release, as run from the project's folder: the project's own CLI when it installs one, otherwise the package runner pinned to the project's Core, such as npx @astryxdesign/cli@0.7.3 init. It used to pin the release of the CLI that answered the run, whatever the project records. No JSON shape or exit code changes. (#10343)
  • astryx experimental render: a page outside a project now renders. Outside a project (no Core or CLI the folder reads, and no package.json that declares one), the page takes the @astryxdesign/* packages its folder lacks, and the integrations a host approves, from the copy the CLI itself runs with, instead of failing with ERR_RENDER_MISSING_DEPENDENCY. React and StyleX come from that copy too, so the page loads one copy of each, even in a React app that installs its own. When that copy's Core cannot be downloaded, a page that needs it fails with ERR_VERSIONS_UNAVAILABLE, as other commands that read Core do. Inside a project, the page uses only the project's own packages. (#10362)
  • A link to a topic that an integration replaces under the same name opens the replacement. In an app whose integration replaced theme or getting-started, doctor reported Core's links to them as naming no doc. (#10342)
  • swizzle no longer copies a component's browser test harnesses (*.spec.ts, *.spec.tsx, such as Item's ItemMarkerColumns.a11y.chromium.spec.ts) when the installed Core source holds them: @astryxdesign/core 0.7.5 and earlier, or Core's repository source. They import Playwright and an unpublished test package, so a project that swizzled such a component failed to type-check or build. Core 0.7.6 and later ship no harnesses, so swizzling from them is unchanged. (#10230)
  • astryx theme build no longer depends on the order it loads the core component docs. A parent doc that lists a sub-component by name only, such as Avatar.doc.mjs listing AvatarStatusDot, erased the values the sub-component's own doc declares when it loaded after that doc; when Avatar.doc.mjs loaded last, avatar-status-dot variant:success counted as a custom value. The build now merges every doc's entry for a component. (#10288)
  • astryx integration verify no longer reports theme_module_stale for a theme whose built module differs only in the command its comment says built it, such as a theme built with yarn astryx and verified where pnpm exec astryx runs. Any other difference still fails. (#10344)
Performance
  • A compact or full hook list, and the suggestions for an unknown hook name, list each of Core's folders once. Before, they listed a folder again for each hook they looked up. (#10324)
  • A search, build or component read lists each folder once. A process that runs several reads, such as a docs site's search or an agent harness, reuses a folder's listing once the folder has stayed unchanged for two seconds. A later read lists the folder again after an entry is added, removed or renamed. (#10274)
  • Within one operation, component discovery reads each component doc once, and the component matcher looks for each component's doc once, not once for each name they resolve. Resolving 30 names that only the matcher finds, such as names in another case, makes 14,794 file-system calls instead of 305,108. Results are unchanged. (#10277)
Documentation
  • The Authoring guides (Quick Start, Field reference, Building Blocks, Ship, Help, and Make your integration work globally) now carry the keyword "authoring", so astryx search authoring lists them right after the Authoring overview instead of after API function pages. (#10354)
  • astryx build --help lists every value --type accepts (component, hook, doc, template, theme), matching the invalid-type error and what build actually runs, and says that doc and theme give an empty kit, since the kit has no doc or theme group. A test keeps the help text, the choices, the API doc and the error message on build and search naming the same set, and checks what each value returns. (#10361)
  • Getting Started has an Upgrade section: upgrade every Astryx package your app lists in one command, to the same release, then run astryx upgrade. If your package manager holds new releases back, exempt the whole @astryxdesign/* scope, not only some of its packages. (#10241)
  • The custom theme guide names the files of a local theme, including the same-stem descriptor theme add reads. (#10347)
  • The CLI's bundled colour token docs say the status icon colours (--color-icon-<status>) paint status marks on the page or a card, such as a StatusDot. (#10204)
  • New block, "Table — Selection in the Leading Mark": row selection with no checkbox column. Each row shows its avatar, and the checkbox takes the avatar's slot while a mouse is over it, on keyboard focus, and on every row once anything is selected. On touch screens the checkbox always shows. It uses the existing useTableSelectionState and renders the checkboxes in the name column, so no new Table API is involved. (#10395)
Other Changes
  • Internal: the export reader can report type-only exports and map a module's whole public surface in one pass. No change to any command's output. (#10365)
Contributors
Thanks to everyone who contributed to this release:

0.7.10

New Features
  • astryx discover lists the experimental PageControl component from @astryxdesign/lab. (#9684)
  • createDragToSnapPoints and its hook useDragToSnapPoints let a drag move an element along one axis and settle it on snap points (px offsets from its resting position) at the release: the nearest one, the next one in its direction after a flick faster than flickThreshold (default 1008 px/s), or the one it started from when the release moves back. The settle continues the release velocity, settleTo(index) settles without a drag, and onSettle(index) reports where it landed. createDragToSnapPoints is exported from the package root and useDragToSnapPoints from @astryxdesign/core/hooks; the CLI's templates gain a playing-card example of each. (#8658)
Fixes
  • Inserting a token through ChatComposerInput's handle (insertToken) now reports the new value through onChange once, as typing does, and hides the placeholder. Before, a controlled host's Send button stayed disabled or sent a stale prompt. The ai-chat-landing page template drops the input-event workaround it used to sync the composer after an insert. (#10167)
  • The CLI no longer lists @astryxdesign/theme-neutral, @astryxdesign/lab or @astryxdesign/charts as optional peers. Before, a package manager could keep a theme from an older release as the CLI's peer after an app removed the theme and upgraded Core, and then warn that the theme's Core peer was not met. @astryxdesign/core stays the CLI's one optional peer. In a Yarn Plug'n'Play workspace member, or a pnpm workspace member with hoist: false, a legacy package.json#astryx.theme of neutral now makes astryx component warn that it cannot resolve the theme. Add the theme to the app with astryx theme add neutral instead. (#10232)
Documentation
  • A new useMultiCombobox — Issue Labels example block builds a Labels field on useMultiCombobox: typing filters the labels, the arrow keys move the active option while focus stays in the field, Enter or a click toggles a label and the list stays open, and selected labels show as removable tokens above the field. Copy it with astryx template useMultiComboboxHookUsage <path>. (#9578)
  • A useSnapPaging — Onboarding Pages example block: onboarding cards in a Carousel with hasSnap={useSnapPaging()} move one view per flick, and a switch moves one card per flick through the hook's pages option. Copy it with astryx template CarouselSnapPaging <path>. (#8153)
Contributors
Thanks to everyone who contributed to this release:

0.7.9

Experimental APIs
New Features
  • astryx discover lists the experimental CircleCheckIndicator component from @astryxdesign/lab.
  • astryx theme build keeps a theme's componentIcons slot functions. The built module imports each slot function from the module the theme source imports it from, writes static slot values beside it as JSON, and reads back the same static componentIcons view, so component icon slots resolve the same for the built theme as for the runtime theme. This includes slots inherited from a built, package, or family base. A slot function defined in the theme file still fails the build: move it to its own module and import it. In --family output, a member supplies its own slot functions through a named import of its whole componentIcons map. The module keeps each slot import as the theme source spells it (--icons-specifier rewrites only the icon registry import), so with --out in another directory, a module must answer to that specifier from the output directory.
  • A theme chooses which shared icon a component's own icon role uses, by slot, with defineTheme({componentIcons}). The first slot is code-block-copy: CodeBlock's copy button passes {copied} and, with no theme entry, draws copy, then check while copied. A slot value is a shared icon name, null to hide the icon, a partial {icon, variant, size} request, or a pure function of the slot's state that returns one; a field the request leaves out keeps the component's own value. For the copy button, null hides only the glyph. theme.componentIcons reads back the static values. ComponentIconSlotMap and the slot value types are exported from @astryxdesign/core/Icon. astryx theme build carries static slot values into built themes and fails on a slot function, and astryx component lists a component's slots.
  • createPanGesture(element, {axis?, onPan}) and usePanGesture(ref, {axis?, onPan}) report a drag on an element as values: onPan gets {state, translation, velocity} as the drag begins, changes, ends at the release, or is cancelled, and a finger, a mouse and a pen all drive it. A mouse or pen drag that starts on selectable text selects it instead; give text the drag should move user-select: none. axis limits the drag to 'x' or 'y'; a drag along the other axis is not reported. translation counts from where the drag began, so an element that follows it does not jump, and velocity at ended is the release velocity in pixels per second. The drag claims its touch at UIKit's 10 pt and leaves presses and long presses alone. destroy() removes every listener; the hook creates one pan for the element behind ref and destroys it at unmount.
  • Motion: a theme's tempo now times the springs of touch motion as well as its CSS durations. Each spring keeps its shape and takes tempo times as long, and so does the animated-layout glide. Finger tracking and busy loops stay as measured. A theme with only a duration scale keeps its springs at tempo 1, even inside a theme with a tempo. The springs don't follow character yet. The motion doc says so.
Fixes
  • astryx docs <namespace> <section> loads the project once instead of once for every guide below the namespace, so on a namespace with many guides, such as astryx docs authoring <section>, the read itself takes tens of milliseconds instead of hundreds. The answer is unchanged.
  • A run that takes over a crashed run's release-cache lock now also recognizes the npm install that run left behind by its original command line, as npm shows it before renaming its process, when Node's own file is not named node, such as nodejs or node-linux-x64.
  • The lexical ranker behind astryx build's search ranks the candidates search gathers, reused the same way. A later query in the same folder, for the same type, gathers again only when an input changed. In a long-running caller, a build that follows a build or a search no longer reads every component, hook, doc, template and theme again. A search that follows a build no longer reads them again either. Results are unchanged.
  • Under the Neutral theme, a selected row, a calendar range and the other selected fills on Neutral's surfaces are visible again, and highlighted code lines are stronger. --color-accent-muted matched the surface in dark mode and barely differed from the hover tint in light mode; it is now #d4d4d4 in light and [#474747](https://github.com/meta/astryx/pull/474747) in dark. In dark mode a selected Item, TreeListItem or checked CheckboxListItem row, a numbered Citation and a FileInput dropzone lift their secondary text so it stays readable on the fill; a dropzone's hint is slightly lighter at rest too. Neutral's code comments, operators and punctuation are slightly less muted so they stay readable on a highlighted line. The CLI's Neutral theme template carries the same values.
  • The stock theme's dark-mode accent (--color-accent) is now [#0171](https://github.com/meta/astryx/pull/0171)E3 instead of [#2694](https://github.com/meta/astryx/pull/2694)FE, so white text on an accent fill, such as a primary Button's label at rest, meets 4.5:1 (4.70:1, was 3.11:1). Hovered and pressed primary Buttons improve too (about 4.36:1 and 4.03:1, from under 3:1) but stay under 4.5:1. Light mode keeps [#0064](https://github.com/meta/astryx/pull/0064)E0. Everything else painted with --color-accent in dark mode also darkens: accent fills, focus rings and accent icons. MetadataList's "Show more", Table's sort rank and DateRangeInput's applied preset now use --color-text-accent, so their text stays readable on dark surfaces. The theme template that astryx theme template writes uses the same dark accent, and the generated color token docs list it. To keep the previous look, a theme can set '--color-accent': ['[#0064](https://github.com/meta/astryx/pull/0064)E0', '[#2694](https://github.com/meta/astryx/pull/2694)FE'].
  • astryx swizzle no longer runs gh auth status before it reports: the ready gh issue create line appears when gh is on your PATH, found without running it, so a copy never waits on a process start or on GitHub. The line now also appears when gh is installed but not logged in; running it, gh asks you to log in.
  • astryx swizzle now copies the private attribute owner modules a component imports, and the unexported style modules they need, beside the copy in the package's layout. A swizzled Item, CheckboxList, RadioList or TreeList no longer imports a privateAttributes/*.stylex subpath that @astryxdesign/core does not export. A second swizzle reuses an identical copy and refuses a changed one without --overwrite. The receipt's files and filesCopied include the modules it copied.
  • astryx theme build reads the theme's icon import from the source it loaded: a theme saved in place while it builds now builds with its import, or fails and builds on the next save, instead of producing a module without the import.
  • theme: support CustomTextTypes module augmentation for custom Text variants (#5013)
Performance
  • astryx search and astryx build read Core's exports map once per run, not once per component. With the other readers, a search now reads Core's package.json 10 times instead of 183. Results are unchanged.
  • When no loaded integration ships templates, the integration-issue check no longer imports every Core template doc. astryx doctor in a project whose integrations only ship icon sets now imports none of them.
  • With no integration loaded, the integration-issue check no longer imports every Core template doc. astryx discover, and astryx component without --showcase or --blocks, now import none of them.
  • The integration manifest writer loads the code-rewrite toolkit only when it patches a manifest. astryx component, astryx theme list and astryx doctor outside a project no longer load it, and a component lookup loads about 70 fewer modules.
  • astryx search and astryx build look for a component's doc only in the Core folders whose listing holds its name, not in every folder. A search makes about a quarter of the file checks it made before. Results are unchanged.
  • Outside a project whose config names debug or integrations, astryx --version no longer loads the project, integration and code-rewrite modules. In a folder with no project config, it uses about three quarters less CPU. When no integration is installed, astryx docs and astryx hook --list load the project but not the code-rewrite modules. Output and exit codes are unchanged.
  • astryx search and astryx build work out a query word's forms once per entry they score, not once per word compared. Answers are unchanged.
  • astryx search and astryx build compute a typo's edit distance only up to the most edits that can count. A fuzzy match now computes far fewer table cells, with unchanged answers.
  • A standalone astryx theme build against the current Core loads Core's root entry only when the theme imports it. A theme that imports only @astryxdesign/core/theme no longer loads all of Core and its components. Family builds and builds against an older Core still load the root. Some builds hand the theme its Core: family builds, builds against an older Core, and themes whose folder has no Core. There, a theme that imports a Core root require() cannot load, such as one that awaits at its top level, fails with ERR_THEME_LOAD. The error names that root.
  • astryx doctor's theme checks, family builds and builds against an older Core defer an installed Core's root entry. It loads only when the theme or one of its .cjs dependencies imports it. A theme that does not import Core's root no longer loads all of Core and its components for them.
Documentation
  • The calendars guide says Calendar, DateInput, DateRangeInput, and DateTimeInput show the Gregorian calendar unless the application chooses another one. (#9842)
  • Hook docs for useCalendarDays, so astryx hook useCalendarDays and astryx search return it, and a useCalendarDays — Month Grid example block: a compact month table built from the hook's weeks and dayNames, with the previous and next months' days dimmed and a Week starts on control (Sunday or Monday) that reorders both the header and the grid. Copy it with astryx template useCalendarDaysHookUsage <path>.
  • Hook docs for useIcon, so astryx hook useIcon and astryx search return it, and a useIcon — Status Row example block: a custom status row draws the success, warning and error icons with useIcon, and under a Theme that overrides those icons the same row draws the theme's icons. Copy it with astryx template useIconHookUsage <path>.
  • Hook docs for useLinkComponent, so astryx hook useLinkComponent and astryx search return it, and a useLinkComponent — Article Cards example block: custom Article cards render their title link with the component the hook resolves. Inside a LinkProvider wired to a client-side router the title navigates without a page load, as="a" gives a native anchor even inside the provider, and outside the provider the title falls back to the next provider up or a native anchor. Copy it with astryx template useLinkComponentHookUsage <path>.
  • Hook docs for useOverlay, so astryx hook useOverlay and astryx search return it, and a useOverlay — Product Quick View example block: a product Card spreads the hook's containerRef and containerProps and renders the returned scrim once over its image. Hovering the card, or moving keyboard focus into it, reveals a Quick view button, and the image link before it lets Tab reach the button. Copy it with astryx template useOverlayHookUsage <path>.
  • Hook docs for useTableSortableState, so astryx hook useTableSortableState and astryx search return it, and a useTableSortableState — Multi-Sort Orders example block: an orders Table with no sort code of its own, where clicking Customer and then Shift-clicking Total sorts by customer and then by total. Copy it with astryx template useTableSortableStateHookUsage <path>.
  • Internationalization gains a short Other calendars guide: choose a calendar on InternationalizationProvider or Calendar, values stay Gregorian ISO dates, and most calendars need Temporal (load temporal-polyfill/full/global where it is missing). A new astryx docs calendars namespace has the detail: the supported calendars, loading Temporal on the server and in the browser, why the lunisolar calendars (chinese, dangi) can differ by a day between runtimes, and ISO 8601 week numbers. The guide and Calendar's calendar prop docs say how to get identical server and browser markup for those calendars: installImplementation() from temporal-polyfill/full/shim on both sides, since the full/global import keeps a native Temporal.
  • InfoTip: the component page, astryx component InfoTip --showcase, and astryx component InfoTip --blocks now have worked examples — a showcase metric label, a row of metric definitions, and read-only settings with permission notes. InfoTip's docs list its anatomy (trigger button, info icon, help surface) and say it follows the toggletip pattern: the button reports aria-expanded="true" while the help is pinned, and a screen reader hears the help once when it pins.
  • The usePanGesture page opens with a draggable box in two forms side by side: the hook and createPanGesture, which takes any element, with the same StyleX styles and Astryx tokens. The playing card follows as the advanced example. The createPanGesture page points to that example, and the usePanGesture guidance warns against holding the drag offset in a large component's state.
  • A new useClickableContainer — Clickable Project Card example block makes a project card clickable anywhere with useClickableContainer: a click on the card follows its title link, while the Star button, the owner link and a text selection keep their own behavior, and Ctrl/Cmd+click or middle-click opens the project in a new tab. Copy it with astryx template useClickableContainerHookUsage <path>.
  • A new useImageMode — Photo Caption example block shows a caption over a photo's sky. useImageMode samples only the strip under the caption, and MediaTheme gives the caption light or dark text from the result. A Beach photo switch swaps a night photo for a bright beach photo, and the caption keeps the dark fallback while the new photo loads. Copy it with astryx template useImageModeHookUsage <path>.
  • A new useInputContainer — Search Field Wrapper example block builds a custom search field with a leading search icon, padding and a trailing Clear button. useInputContainer puts focus in the input when the icon or the padding is clicked, and a click on Clear stays with Clear. Copy it with astryx template useInputContainerHookUsage <path>.
  • A useMergedRefs — AutoGrowTextArea example block: an AutoGrowTextArea forwards the caller's ref and keeps its own ref to measure its height, and the merged ref attaches both to the same textarea, so it resizes itself while a parent button focuses it through the forwarded ref. Copy it with astryx template useMergedRefsHookUsage <path>.
  • A new useScrollLock — Full-screen Mobile Menu example block opens a custom full-screen menu from a Menu button and locks the page behind it with useScrollLock, so the page neither scrolls nor shifts sideways, and closing the menu returns the reader to the same scroll position. Copy it with astryx template useScrollLockHookUsage <path>.
  • A new useScrollOverflow — Filter Strip Edge Fades example block shows a row of active filters that scrolls sideways and fades only the edge where useScrollOverflow reports hidden filters. Adding or removing a filter updates the fades, and a right-to-left switch moves the start edge to the right. Copy it with astryx template useScrollOverflowHookUsage <path>.
Other Changes
  • Internal: the search gather runs in its own listing-cache operation, so a caller that gathers candidates directly lists each folder about once, as astryx search already does. The command's results and output are unchanged. Not exported from the package entry point.
  • Internal: the CLI's in-process test helper builds only the commands its arguments need, as a run of the bin does.
  • The CLI's test setup rebuilds Core when its build is older than Core's sources or translations. It does so before any test starts, so a reused checkout no longer tests the CLI against an old Core build. A test waiting on another's build reads it only once that build is finished. One checkout's build no longer holds up another's tests. A run that cannot rebuild a stale Core, while an earlier run in the checkout uses it, stops with an error naming that run.
  • The PowerSearch blocks fit a phone-sized screen. Each sizes its field through a grid column, minmax(0, <width>): the old width where there is room, and the container's width where there is not. The Search with Table block's table scrolls inside its own frame on a narrow screen instead of widening the example.
  • Internal: the main searcher's test checks the count contract for each query, not a byte total over eight queries.
  • The Tokenizer blocks and the table-inbox and work-item-detail page templates follow Tokenizer's 'adaptive' default, so on a compact touch screen they show the bottom sheet. Their endContent and renderToken work there as in the inline field; hasClear and the overflow modes apply to the inline field, and the Clear and Overflow blocks say so. The rule: docs examples follow adaptive; the stories that are fixtures for inline-field geometry (Caret placement, Logical order, RTL end lane, Long token beside the end lane) keep presentation="popover". The table-inbox and work-item-detail back arrows mirror in right-to-left.
Contributors
Thanks to everyone who contributed to this release:

0.7.8

Experimental APIs
  • astryx discovery lists the lab's new SelectableCardGroup.
New Features
  • In Chrome on Android, on a touch screen, a Tall BottomSheet places the focused field just above the on-screen keyboard when Chrome reports it, then rides the rest of Gboard's slide; through the hide the sheet's scroll room stays while its content rides down, so nothing jumps while the keyboard is still on screen. Under Reduce Motion it cross-fades instead of moving. The browser-support guide says so.
  • A component doc can mark its component deprecated with deprecated: {replacement, description}: the name of the component to use instead and the modernization route. astryx search results and astryx build kit entries for that component carry the field as deprecated (a deprecated: line in their text output), and the docsite shows a Deprecated badge in the component's page header (beside any stability badge) and a notice at the top of its page that names and links the replacement, and labels it Deprecated on its components index tile and in site search. BottomSheetSwitcher sets it, naming BottomSheet; the component keeps working unchanged.
  • createAnimator(element) and its hook useAnimator(ref) animate one element with the motion Astryx's components use; the hook takes the element's ref, so a gesture hook can share the element. animate springs x, y, scale, rotate and opacity to a target on the state-change motion, decay coasts any of them from a release velocity, set jumps, get and getVelocity read, and stop halts; animate and decay return a promise. Reduce Motion is planned for every call. createAnimator is exported from the package root and useAnimator from @astryxdesign/core/hooks; the CLI's templates gain a playing-cards example of each.
  • astryx upgrade gains the promote-tokenizer-presentation codemod. It rewrites a static experimental={{presentation: x}} on Tokenizer, the 0.7.7 spelling that Tokenizer no longer reads, to presentation={x}. Where it cannot prove the rewrite, including any Tokenizer that spreads props (a spread may also set presentation), it leaves the call unchanged with a TODO.
Fixes
  • astryx component takes a component's exact name in another case as that component's, never a module's that only shares the spelling. tokenizer opens Tokenizer's doc instead of CodeBlock's, which it reached through CodeBlock/tokenizer.ts. --source with tokenizer, slider, switch or progressBar no longer prints CodeBlock/tokenizer.ts or the motion tables in motion/uikit/, and answers ERR_NO_SOURCE, as --source badge does.
  • The theme token --duration-exit, the standard dismissal duration, now exists. It defaults to var(--duration-fast), so it follows a theme's tempo through that token, and a theme can set it like any duration token. Before, a theme or component that read var(--duration-exit) found no value. The motion and token docs, and the theme template's token list, name it.
Performance
  • integrationComponentConflicts(), integrationDocConflicts() and integrationCheck() from @astryxdesign/cli/api, and doctor integration components, doctor integration docs and integration check, find Core's components from the folder listings they already read, with far fewer file system calls. Their results are unchanged.
  • A run of astryx loads only the command it names, so it starts with less work: astryx --version uses about 0.31 s less CPU, and astryx docs --json, astryx component --list and astryx theme build about 0.25–0.3 s less. Help, the manifest and an unknown command still load every command. Output and exit codes are unchanged.
  • astryx search and astryx build parse a page template's source for the components it renders only when the query could match one of them. A query no page renders parses only the few pages whose source holds an escape, and a first search for it uses about 20% less CPU. A query whose words name components on most pages still parses most of them and can take up to about 4% more. Results are unchanged.
Documentation
  • The browser-support guide has a section on the on-screen keyboard: a fully expanded Tall BottomSheet measures it as the layout viewport's height minus the visual viewport's, and keeps the focused field above it in Safari on iOS, Firefox for Android and Chrome on Android. In Chrome, by default (interactive-widget=resizes-visual), the sheet adds its scroll room once Chrome reports the keyboard; with interactive-widget=resizes-content Chrome shrinks the page for the keyboard itself and the sheet changes nothing. Your app owns its viewport <meta> element; Astryx never sets it.
  • Hook docs for useLightbox, so astryx hook useLightbox and astryx search return it, and a useLightbox — Gallery Grid example block: a grid of photo thumbnails that opens a fullscreen gallery at the clicked item.
  • A new useAnnounce — Filter Result Count example block shows the hook on a product filter: once typing pauses for 500 ms, a screen reader hears the result count ("3 results", or "No results"). The count has its own hasReplace instance, as the hook's docs advise for a changing value. Copy it with astryx template useAnnounceHookUsage <path>.
  • A new useClipboard — Share Link example block shows the hook on a share card: Copy writes the invite link, the button reads "Copied" while isCopied is true and resets on the hook's timer, and a screen reader hears "Link copied". Copy it with astryx template useClipboardHookUsage <path>.
  • A new useFocusTrap — Quick Edit Panel example block traps focus in a custom quick-edit panel that is not built on Dialog: focusFirst moves focus to its field on open, Tab and Shift+Tab stay inside it, Escape closes it through onEscape, and closing returns focus to the Quick edit button. Copy it with astryx template useFocusTrapHookUsage <path>.
  • A new useHotkeys — Search and Help Shortcuts example block shows the hook on a page header: "/" focuses the search field and "?" opens the shortcut help, typing either character in the field does not trigger them, and a switch turns the single-key shortcuts off through isDisabled. Copy it with astryx template useHotkeysHookUsage <path>.
  • A new useInputStatusIcon — Coupon Code Status example block shows a custom bordered input that takes its status affordance from useInputStatusIcon: a wrong code shows the error status and the valid code shows success, and the variant switch moves between a glyph with a message below (attached), no icon on the field (detached), and a focusable button with a tooltip that keyboard and screen-reader users can reach (tooltip). Copy it with astryx template useInputStatusIconHookUsage <path>.
  • The useKeyboardHint — Arrow-key Hint example block now calls useKeyboardHint itself instead of relying on Toolbar, which calls the hook internally. It is a five-star rating with one Tab stop, where Left and Right change the rating: tabbing into it shows the "← → to navigate" hint, the first arrow press dismisses it, and tabbing back in does not show it again. Copy it with astryx template useKeyboardHintHookUsage <path>.
  • A new useLocale — Invoice Summary example block formats an invoice date and amount with Intl using the locale from useLocale, so switching the provider from English to German changes "Nov 2, 2026 · $1,234.50" to "2. Nov. 2026 · 1.234,50 $" with no second locale source. Copy it with astryx template useLocaleHookUsage <path>.
  • A new useScrollableArea — Activity Log Panel example block shows a fixed-height Activity log whose entries scroll. useScrollableArea makes the panel a keyboard tab stop only when its entries overflow, shows a top or bottom edge shadow only where entries are hidden, and stops a scroll at the end from scrolling the page. Add entry flips it from not scrollable to scrollable. Copy it with astryx template useScrollableAreaHookUsage <path>.
  • A new useTreeFocus — Keyboard File Tree example block builds a small file tree from plain rows with tree roles and gives it the WAI-ARIA tree keyboard model with useTreeFocus: arrow keys move over the visible rows and open, enter, leave or close folders, Home and End jump to the ends, a typed letter jumps to a matching name, Enter opens a file, and one row is the tab stop. Copy it with astryx template useTreeFocusHookUsage <path>.
  • A new useTypeahead — Type to Focus a Country example block adds type-to-focus to a country list of buttons. Typing "can" focuses Canada, pressing "b" again and again cycles through Belgium, Brazil and Bulgaria, and "e" finds Éire with the accent ignored. useTypeahead reports each match through onMatch, and useListFocus moves focus. Copy it with astryx template useTypeaheadHookUsage <path>.
Other Changes
  • Internal: the file read behind astryx doctor --built takes its file limit as an option, 20,000 unless a caller passes one, and the checks' messages name the limit the read used. The command's checks and output are unchanged. Not exported from the package entry point.
  • astryx discover no longer lists the Lab components MobileTokenizer and MobilePowerSearch, which are removed from @astryxdesign/lab; their touch flows are Core's Tokenizer and PowerSearch presentation sheets.
  • Internal: the public-import check's declaredTargets and missingNames are exported from their foundation module, so the docsite's production registry judges a copied example's imports by the same rule. The CLI's checks and their output are unchanged. Not exported from the package entry point.
  • Internal: a gap-report handler's time budget starts once its module has loaded. Starting its worker and loading the module have the default deadline, so a short budget in a contract test no longer covers a slow start on a busy machine. The 30-second handler budget is unchanged.
  • Internal: generating the CLI's type declarations no longer fails when builds in two checkouts run at once on one machine, and it no longer needs pnpm on PATH.
  • The Tokenizer blocks and page templates that show a prop the bottom sheet does not render (hasClear, endContent, tokenOverflowBehavior, hasEntriesOnFocus, renderToken) pass presentation="popover", so they keep the inline field on phones under Tokenizer's new 'adaptive' default.
Contributors
Thanks to everyone who contributed to this release: