@astryxdesign/cli 0.7.12-canary.f36bd72 → 0.7.12

package/api/search/_fit-order.mjs

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A last pass over a searcher's answer: inside each run of one score
+ * band and kind, the entries from #2 to #10 that fit the whole query much
+ * worse than the others in their run move, in order, after them.
+ * @input the ordered response, the gathered candidates, and the query
+ * @output the same response with the same results, maybe in a new order
+ * @position api/search; rankWith (_main-searcher.mjs) runs it after
+ * orderMatches, with the weights the adapter loads (loadSearchData) through
+ * build's own loader. The fit is build's block-picker match
+ * (build/blocks/blocks.mjs) with its shipped weights, so an entry the weights
+ * never saw is scored from its own docs the same way. Without readable
+ * weights the order stays.
+ */
+
+import {
+  docSideOf,
+  matchOf,
+  requestSideOf,
+  stemOf,
+  termsOf,
+  wordsOf,
+} from '../build/blocks/blocks.mjs';
+import {bandOf} from './_order.mjs';
+import {searchedComponentsOf} from './_result.mjs';
+
+/** An entry stays in place when its fit is at least this times the median. */
+export const FIT_BAR = 1.7;
+
+/** An entry whose name spells at least this many query words never moves. */
+const NAME_WORDS = 2;
+
+/** The first result stays; the pass orders the places after it up to here. */
+export const FIT_PLACES = 10;
+
+/** @typedef {import('../build/blocks/blocks.mjs').BlockPickerWeights} Weights */
+/** @typedef {{vector: Map<number, number>, projected: Float64Array}} Side */
+
+/**
+ * Each candidate by `domain:name`; a doc also by its topic and by
+ * `topic#section`. The first candidate with a key owns it.
+ * @type {WeakMap<any[], Map<string, any>>}
+ */
+const keyed = new WeakMap();
+
+/**
+ * Each candidate's docs side, computed when a result first needs it.
+ * @type {WeakMap<Weights, WeakMap<any, Side>>}
+ */
+const sides = new WeakMap();
+
+/**
+ * An entry's docs text: its name words, display name or first title,
+ * description, and keywords.
+ * @param {any} c
+ */
+const docText = c =>
+  [
+    wordsOf(c.name).join(' '),
+    c._displayName ?? (Array.isArray(c.titles) ? c.titles[0] : '') ?? '',
+    c.description ?? '',
+    (Array.isArray(c.keywords) ? c.keywords : []).join(' '),
+  ].join(' ');
+
+/**
+ * @param {any[]} candidates
+ * @returns {Map<string, any>}
+ */
+function keysOf(candidates) {
+  let byKey = keyed.get(candidates);
+  if (!byKey) {
+    byKey = new Map();
+    for (const c of candidates) {
+      const keys = [`${c.domain}:${c._resultName ?? c.name}`];
+      if (c.domain === 'doc' && c._topic)
+        keys.push(
+          c._section ? `doc:${c._topic}#${c._section}` : `doc:${c._topic}`,
+        );
+      for (const k of keys) if (!byKey.has(k)) byKey.set(k, c);
+    }
+    keyed.set(candidates, byKey);
+  }
+  return byKey;
+}
+
+/**
+ * @param {any} c
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function candidateSide(c, weights) {
+  let byCandidate = sides.get(weights);
+  if (!byCandidate) {
+    byCandidate = new WeakMap();
+    sides.set(weights, byCandidate);
+  }
+  let side = byCandidate.get(c);
+  if (!side) {
+    side = docSideOf(docText(c), weights);
+    byCandidate.set(c, side);
+  }
+  return side;
+}
+
+/**
+ * A result's docs side: its candidate's, else one from the result's own name,
+ * display name and description.
+ * @param {any} r
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function resultSideOf(r, candidates, weights) {
+  const byKey = keysOf(candidates);
+  if (r.domain === 'doc' && r.section) {
+    const c = byKey.get(`doc:${r.name}#${r.section}`);
+    if (c) return candidateSide(c, weights);
+  }
+  const c = byKey.get(`${r.domain}:${r.name}`);
+  return c
+    ? candidateSide(c, weights)
+    : docSideOf(
+        `${wordsOf(r.name).join(' ')} ${r.displayName ?? ''} ${r.description ?? ''}`,
+        weights,
+      );
+}
+
+/**
+ * A result's run: its score band and kind (doc or not), as orderMatches reads
+ * them.
+ * @param {any} r
+ */
+const runOf = r => `${bandOf(r.score ?? 0)}:${r.domain === 'doc'}`;
+
+/**
+ * The results with the first kept. Entries #2 to #10 split into runs of one
+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR
+ * times the run's median fit move, in order, after the others, unless their
+ * name spells NAME_WORDS or more of the query's words. A run whose
+ * median fit is zero or less keeps its order. Nothing crosses a run, and
+ * nothing is added or dropped.
+ * @param {any[]} results
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ *   the block picker's weights, or a function that reads them; the function
+ *   runs only when a run can change. Without weights the order stays
+ * @returns {any[]}
+ */
+export function orderByFit(results, candidates, query, weights) {
+  if (!weights || results.length < 3) return results;
+  const end = Math.min(FIT_PLACES, results.length);
+  /** @type {[number, number][]} */
+  const runs = [];
+  for (let i = 1; i < end;) {
+    let j = i;
+    while (j < end && runOf(results[j]) === runOf(results[i])) j++;
+    runs.push([i, j]);
+    i = j;
+  }
+  // Only a run of two or more can change, so the weights stay unread when
+  // there is none.
+  if (!runs.some(([i, j]) => j - i > 1)) return results;
+  const w = typeof weights === 'function' ? weights() : weights;
+  if (!w) return results;
+  const request = requestSideOf(query, w);
+  const queryWords = new Set(termsOf(query).filter(t => !t.includes('_')));
+  /** @param {any} r */
+  const named = r =>
+    new Set(
+      wordsOf(r.name)
+        .map(stemOf)
+        .filter(word => queryWords.has(word)),
+    ).size >= NAME_WORDS;
+  const out = results.slice();
+  let changed = false;
+  for (const [i, j] of runs) {
+    if (j - i < 2) continue;
+    const moved = demoteWeak(
+      results.slice(i, j),
+      request,
+      candidates,
+      w,
+      named,
+    );
+    moved.forEach((r, k) => {
+      if (r !== out[i + k]) changed = true;
+      out[i + k] = r;
+    });
+  }
+  return changed ? out : results;
+}
+
+/**
+ * One run, with the entries under FIT_BAR times its median fit moved, in
+ * order, after the others. An entry whose name spells NAME_WORDS or more of
+ * the query's words stays with the others: its name is strong evidence.
+ * @param {any[]} run
+ * @param {Side} request
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @param {(r: any) => boolean} named
+ * @returns {any[]}
+ */
+function demoteWeak(run, request, candidates, weights, named) {
+  const fits = run.map(
+    r => matchOf(request, resultSideOf(r, candidates, weights), weights).match,
+  );
+  const sorted = [...fits].sort((a, b) => a - b);
+  const n = sorted.length;
+  const median =
+    n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;
+  if (!(median > 0)) return run;
+  const bar = FIT_BAR * median;
+  const kept = run.map((r, k) => fits[k] >= bar || named(r));
+  return [...run.filter((_, k) => kept[k]), ...run.filter((_, k) => !kept[k])];
+}
+
+/**
+ * The search response with its results ordered by fit (`orderByFit`). Any
+ * other response passes through.
+ * @template T
+ * @param {T} response
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ * @returns {T}
+ */
+export function withFitOrder(response, candidates, query, weights) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results)) return response;
+  const ordered = orderByFit(results, candidates, query, weights);
+  if (ordered === results) return response;
+  const out = {...r, data: {...r.data, results: ordered}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}
+
+/**
+ * The search response with at most `limit` results.
+ * @template T
+ * @param {T} response
+ * @param {number} limit
+ * @returns {T}
+ */
+export function withLimit(response, limit) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results) || results.length <= limit) return response;
+  const out = {...r, data: {...r.data, results: results.slice(0, limit)}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}

package/api/search/_main-searcher.mjs

@@ -15,6 +15,7 @@
 import {routeKit} from '../../foundation/route/route.mjs';
 import {rank, signals} from './_features.mjs';
 import {entryTable} from './_entries.mjs';
+import {FIT_PLACES, withFitOrder, withLimit} from './_fit-order.mjs';
 import {orderMatches} from './_order.mjs';
 import {routeProbs} from './_query-words.mjs';
 import {namesWhole, rankLexical} from './_lexical.mjs';
@@ -94,13 +95,22 @@ export function rankWith(request, catalog, weights) {
   );
   const route = routeProbs(catalog.data.router, query);
   const rows = signals(table, query, lexical.data.results, route);
-  return orderMatches(
-    table,
-    rank(table, rows, weights),
-    lexical,
+  const limit = options.limit ?? 20;
+  // The fit pass reads the first FIT_PLACES results at every limit, so a
+  // smaller limit shows the top of that order.
+  const ordered = withFitOrder(
+    orderMatches(
+      table,
+      rank(table, rows, weights),
+      lexical,
+      query,
+      Math.max(limit, FIT_PLACES),
+    ),
+    catalog.all,
     query,
-    options.limit ?? 20,
+    () => catalog.data.picker,
   );
+  return withLimit(ordered, limit);
 }
 
 /** @type {import('./tree.mjs').SearchKit} */

package/api/template/skeleton/skeleton.mjs

@@ -146,7 +146,7 @@ function extractSkeleton(source) {
 
     // Match a JSX opening tag, e.g. `<Section` or the legacy `<XDSSection`.
     // The `XDS` prefix is optional (templates author bare names post
-    // un-prefix migration P2380608025). `tagName` is the full authored name
+    // un-prefix migration). `tagName` is the full authored name
     // (used for the self-closing lookahead); `comp` is the bare display name.
     const openMatch = t.match(/^<((XDS)?([A-Z]\w+))/);
     if (openMatch && !t.startsWith('</')) {

package/assets/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Codemod: Drop the `XDS` prefix from @xds/core imports and their usages
  *
- * Part of the XDS-prefix migration (P2380608025). Rewrites consumer code from
+ * Part of the XDS-prefix migration. Rewrites consumer code from
  * the prefixed names to their bare equivalents:
  *
  *   XDSButton      -> Button

package/assets/codemods/transforms/v0.1.0/index.mjs

@@ -24,7 +24,7 @@ import migrateXdsCssSurfaces, {
 
 export default [
   {
-    // XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
+    // XDS-prefix migration. Mandatory in v0.1.0: the release
     // dropped the prefixed compatibility aliases (useXDSTheme, XDSButton,
     // XDSIconRegistry, ...), so consumers upgrading from 0.0.x MUST rewrite
     // prefixed imports to their bare names.

package/assets/docs/tree/icon-sets.doc.mjs

@@ -61,7 +61,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
+          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. After you rename the package, the next command that writes the data file (`new-set` on the existing set, with or without `--from`, `add`, `map`, or `new-definition --icon`) writes the new name and keeps any subpath (`@acme/old-icons/outline` becomes `@acme/new-icons/outline`), and its receipt says so. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
         },
         {
           type: 'prose',
@@ -121,7 +121,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
+          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). An export name cannot start with a digit, so an icon whose id would start with one once the library prefix comes off keeps the prefix (`fa0` is id `fa-0`, exported as `Fa0Icon`), and an id you give with `--id` must start with a letter. `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
         },
         {
           type: 'prose',
@@ -139,11 +139,11 @@ astryx experimental icon add --variant solid --from @heroicons/react/24/solid --
         },
         {
           type: 'prose',
-          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. Running it again changes nothing.",
+          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. A library may ship each look as its own package (Font Awesome's solid and regular packages): `--from` may then name the other package, and an icon gains the variant from the export of the same name there; the receipt lists the icons that package has no export for. Running it again changes nothing.",
         },
         {
           type: 'prose',
-          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
+          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either, and neither is a pack: an object whose keys are all other exports of the module, such as `fas` next to `faXmark`. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
         },
       ],
     },

package/assets/docs/tree/render-pages.doc.mjs

@@ -67,7 +67,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering.',
+          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering. A `node-crash` warning names a Node build that crashes in `Intl.Segmenter` (its version and path). The page rendered without it, so the output may differ slightly: initials and character counts (such as Avatar initials) can split a joined emoji, a flag, or a letter written with a separate accent mark. Names in ordinary composed letters (`José`, `Zoë`, `李小龙`) come out the same. Render with an official Node.js build to remove the difference.',
         },
       ],
     },

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.doc.mjs

@@ -7,8 +7,8 @@ export const doc = {
   name: 'useTableRowsVirtualization - Fixed Height Rows',
   displayName: 'useTableRowsVirtualization - Fixed Height Rows',
   description:
-    'A Table with 1,000 product rows in a fixed-height viewport. Scroll vertically to mount the visible rows. The caller keeps all data and columns; this hook does not virtualize columns.',
+    "A Table with 1,000 product rows inside a 320px-tall parent, which bounds its scroll area. Give the Table's parent a height, fixed or relative, or a flex child, so windowing can bound the rows; with no height every row renders. Scroll vertically to mount the visible rows. The caller keeps all data and columns; this hook does not virtualize columns.",
   isReady: true,
   aspectRatio: 16 / 9,
-  componentsUsed: ['Table'],
+  componentsUsed: ['Table', 'VStack'],
 };

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.tsx

@@ -7,6 +7,7 @@ import {
   useTableRowsVirtualization,
   type TableColumn,
 } from '@astryxdesign/core/Table';
+import {VStack} from '@astryxdesign/core/Layout';
 
 interface Product extends Record<string, unknown> {
   id: string;
@@ -22,14 +23,19 @@ const columns: TableColumn<Product>[] = [{key: 'name', header: 'Product'}];
 export default function RowsVirtualizationHookUsage() {
   const virtualization = useTableRowsVirtualization({
     rowHeight: 56,
-    viewportHeight: 320,
+    initialViewportHeight: 320,
   });
+  // Give the Table's parent a height, fixed or relative, or a flex child, so
+  // windowing can bound the rows; with no height every row renders.
+  // initialViewportHeight only sizes the first window.
   return (
-    <Table
-      data={products}
-      columns={columns}
-      idKey="id"
-      virtualization={virtualization}
-    />
+    <VStack height={320}>
+      <Table
+        data={products}
+        columns={columns}
+        idKey="id"
+        virtualization={virtualization}
+      />
+    </VStack>
   );
 }