@astryxdesign/cli 0.7.11-canary.ed0adf3 → 0.7.12-canary.ccb4a6d

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @xds/cli
 
+# 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:
+
+- @cixzhang
+- @josephfarina
+- @thecodebasedot
+- @utsavo-afk
+- @vjeux
+
+---
+
 # 0.7.10
 
 #### New Features

package/api/build/kit/rank.mjs

@@ -41,7 +41,9 @@
  *   `settings`) is that family's default. A variant displaces it only with two
  *   matched terms of its own ("a small comparison note" does not make a
  *   dashboard the comparison dashboard), and a base too weak to start on its
- *   own displaces no variant ("a funnel for a dashboard" is the funnel).
+ *   own displaces no variant ("a funnel for a dashboard" is the funnel) —
+ *   unless the idea names its family in the head, which is start evidence on
+ *   its own ("saml login" stays the login page).
  */
 
 import {
@@ -219,7 +221,8 @@ export function rankPages(query, pages) {
         }
       }
       const familyNamed = namedFamilies.has(family);
-      if (headFamilies.has(family)) score += HEAD_FAMILY;
+      const headNamed = headFamilies.has(family);
+      if (headNamed) score += HEAD_FAMILY;
       else if (familyNamed) score += BODY_FAMILY;
       const base = normalized(page.name) === normalized(family);
       if (familyNamed && base) score += FAMILY_BASE;
@@ -228,6 +231,7 @@ export function rankPages(query, pages) {
         score,
         hits,
         familyNamed,
+        headNamed,
         containerMatched,
         family,
         base,
@@ -246,7 +250,14 @@ export function rankPages(query, pages) {
 /**
  * Put a named family's base template ahead of the variant that outranks it,
  * unless the variant matched START_TERMS terms the base did not, or the base
- * scores too little to start on its own.
+ * cannot start on its own: too little score, or too few matched terms. The
+ * head names the exception: a family word in the idea's head is start
+ * evidence on its own — the same evidence pickStart accepts in place of a
+ * second term — so a head-named one-term base can still take the lead ("saml
+ * login" is the login page, not the SSO flow). A base whose family the idea
+ * names only elsewhere still needs a second term: score alone drifts upward
+ * as the catalog grows (idf rises with page count) and would eventually let a
+ * one-term base displace its variant, while hits do not drift.
  * @param {RankedPage[]} ranked
  * @returns {RankedPage[]}
  */
@@ -254,7 +265,13 @@ function baseFirst(ranked) {
   const top = ranked[0];
   if (!top || top.base || !top.familyNamed) return ranked;
   const base = ranked.find(r => r.base && r.family === top.family);
-  if (!base || base.score < START_SCORE) return ranked;
+  if (
+    !base ||
+    base.score < START_SCORE ||
+    (base.hits < START_TERMS && !base.headNamed)
+  ) {
+    return ranked;
+  }
   const own = [...top.matched].filter(t => !base.matched.has(t)).length;
   return own >= START_TERMS
     ? ranked

package/api/build/kit/words.d.mts

@@ -64,6 +64,7 @@ export type RankedPage = {
     score: number;
     hits: number;
     familyNamed: boolean;
+    headNamed: boolean;
     containerMatched: boolean;
     family: string;
     base: boolean;

package/api/build/kit/words.mjs

@@ -163,7 +163,7 @@ export const SYNONYMS_OF = (() => {
 /**
  * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
  * @typedef {import('../_adapter.mjs').ComponentWords} ComponentWords
- * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
+ * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, headNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
  * @typedef {'page' | 'part' | 'edit'} IdeaKind
  */
 

package/api/icon/_adapter.d.mts

@@ -50,6 +50,7 @@ export { astryxIconDefinitions } from "../../foundation/discovery/icon-definitio
 export { iconSetKey } from "../../foundation/discovery/icon-set-discovery.mjs";
 export { setConfigString } from "../../foundation/config/config-writer.mjs";
 export { exportValueKind } from "../../foundation/discovery/module-exports.mjs";
-export { iconRecord, importLine, leadingReading, matchIcon, rankIcons, scoreIcon } from "../../foundation/discovery/icon-ranking.mjs";
-export { assertIconExport, checkNewDefinition, definitionFile, findLocalIconSet, writeDefinitionFile, iconIdOf, closestNames, libraryIcons, mappableDefinitions, resolveIconSource, generatedModulePath, generatedNamesOf, generatedOrigins, iconModulePackage, sameIconModule, iconExportName, iconNaming, modulePrefix, setModuleNote, variantExportName, writeGeneratedIcons, writeIconSetData, definitionNameOf, iconIdIn, iconsWithWord, localSourceNote, THEME_MAP_NAME } from "../../foundation/discovery/icon-set-writer.mjs";
+export { iconRecord, importLine, leadingReading, matchIcon, answeringMatches, rankIcons, scoreIcon } from "../../foundation/discovery/icon-ranking.mjs";
+export { assertIconExport, checkNewDefinition, definitionNameFromInput, definitionFile, findLocalIconSet, writeDefinitionFile, iconIdOf, closestNames, libraryIcons, mappableDefinitions, resolveIconSource, generatedModulePath, generatedNamesOf, generatedOrigins, iconModulePackage, sameIconModule, iconExportName, iconNaming, modulePrefix, moduleNaming, iconNamingWithoutLook, splitLook, setModuleNote, variantExportName, writeGeneratedIcons, writeIconSetData, definitionNameOf, iconIdIn, iconsWithWord, localSourceNote, THEME_MAP_NAME } from "../../foundation/discovery/icon-set-writer.mjs";
 export { addIconDefinition, addIconSet } from "./_authoring.mjs";
+export { checkVariantLook, drawnLooks } from "./_default-look.mjs";

package/api/icon/_adapter.mjs

@@ -6,8 +6,8 @@
  *
  * @position api/icon — adapter for api/icon/{search,detail,list,use,map,add,
  *   new-set,new-definition}; it also carries the icon ranking, the icon-set
- *   writer, the set and definition authoring writes, and the config writer
- *   the leaves use
+ *   writer, the set and definition authoring writes, the default-look
+ *   rule, and the config writer the leaves use
  */
 
 import * as fs from 'node:fs';
@@ -28,6 +28,7 @@ export {
   importLine,
   leadingReading,
   matchIcon,
+  answeringMatches,
   rankIcons,
   scoreIcon,
 } from '../../foundation/discovery/icon-ranking.mjs';
@@ -37,6 +38,7 @@ export {setConfigString} from '../../foundation/config/config-writer.mjs';
 export {
   assertIconExport,
   checkNewDefinition,
+  definitionNameFromInput,
   definitionFile,
   findLocalIconSet,
   writeDefinitionFile,
@@ -53,6 +55,9 @@ export {
   iconExportName,
   iconNaming,
   modulePrefix,
+  moduleNaming,
+  iconNamingWithoutLook,
+  splitLook,
   setModuleNote,
   variantExportName,
   writeGeneratedIcons,
@@ -65,6 +70,7 @@ export {
 } from '../../foundation/discovery/icon-set-writer.mjs';
 export {exportValueKind} from '../../foundation/discovery/module-exports.mjs';
 export {addIconDefinition, addIconSet} from './_authoring.mjs';
+export {checkVariantLook, drawnLooks} from './_default-look.mjs';
 
 /**
  * Refuse a command that writes to a project or package when `cwd` is outside

package/api/icon/_authoring.d.mts

@@ -44,3 +44,4 @@ export function addIconDefinition(name: string, options: {
     type: "integration.add";
     data: import("./icon.type.mjs").IconNewData;
 }>;
+export type Looks = import("./_default-look.mjs").Looks;