@astryxdesign/cli 0.7.12-canary.c73b9e4 → 0.7.12-canary.c86484d

package/api/component/__fixtures__/resolutions/modules.txt

@@ -298,7 +298,7 @@ useSpeechRecognition useSpeechRecognition Chat/Chat.doc.mjs Chat/useSpeechRecogn
 useSwipeAction useSwipeAction Item/Item.doc.mjs Item/useSwipeAction.ts
 useSwitchTouch useSwitchTouch Switch/Switch.doc.mjs Switch/useSwitchTouch.ts
 useTableCellStyles useTableCellStyles Table/Table.doc.mjs Table/useTableCellStyles.ts
-useTableColumnSettingsState useTableColumnSettingsState Table/Table.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
+useTableColumnSettingsState useTableColumnSettingsState Table/plugins/columnSettings/useTableColumnSettingsState.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
 useTableSortableState useTableSortableState Table/plugins/sortable/useTableSortableState.doc.mjs Table/plugins/sortable/useTableSortableState.tsx
 useToastGesture useToastGesture Toast/Toast.doc.mjs Toast/useToastGesture.ts
 useTouchTrigger useTouchTrigger Layer/Layer.doc.mjs Layer/useTouchTrigger.ts

package/api/template/template.mjs

@@ -193,6 +193,7 @@ export async function template(name, options = {}) {
       `Unknown template "${name}"`,
       orderByAffinity(name, templates, t => [t.dirName, t.name], {
         closest: true,
+        typos: true,
       }).map(t => ({
         name: t.dirName,
         reason: `${t.type} template`,

package/assets/discover/official-packages.json

@@ -128,6 +128,10 @@
           "kind": "component",
           "name": "CommentThread"
         },
+        {
+          "kind": "component",
+          "name": "DialogHeroHeader"
+        },
         {
           "kind": "component",
           "name": "DiffViewer"
@@ -136,6 +140,10 @@
           "kind": "component",
           "name": "EmojiPicker"
         },
+        {
+          "kind": "component",
+          "name": "LineClamp"
+        },
         {
           "kind": "component",
           "name": "ListInput"
@@ -252,6 +260,10 @@
           "kind": "template",
           "name": "CommentThreadShowcase"
         },
+        {
+          "kind": "template",
+          "name": "DialogHeroHeaderShowcase"
+        },
         {
           "kind": "template",
           "name": "DiffViewerShowcase"

package/assets/docs/tree/type-scale.doc.mjs

@@ -2,7 +2,8 @@
 
 /**
  * @file `astryx docs typography/type-scale`: line height, semantic type scale,
- * display text, headings and text components, and custom type scales.
+ * display text, headings and text components, custom type scales, and the
+ * reader's text size on iOS.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -14,13 +15,15 @@ export const docs = {
   placement: {parent: 'namespace:typography', slot: 'guides', order: 20},
   category: 'foundations',
   description:
-    'Line height, semantic type scale tokens, display text, Heading and Text components, and custom type scales via defineTheme.',
+    "Line height, semantic type scale tokens, display text, Heading and Text components, custom type scales via defineTheme, and following the reader's text size on iOS.",
   keywords: [
     'line height',
     'leading',
     'defineTheme',
     'base',
     'ratio',
+    'dynamic type',
+    'text size',
   ],
 
   sections: [
@@ -143,5 +146,19 @@ const denseTheme = defineTheme({
         },
       ],
     },
+    {
+      id: 'dynamic-type',
+      title: "Following the reader's text size on iOS",
+      content: [
+        {
+          type: 'prose',
+          text: "On iPhone, readers pick a text size in Settings (Display & Text Size, then Larger Text), and native apps grow or shrink their text with it. Every theme does the same in Safari on iPhone, which exposes that choice through `font: -apple-system-body`: each font size follows the reader's choice on the curve of the iOS text style it plays, so body text scales like Body, `heading-1` like Title 1 and display text like Large Title, and every role keeps its order. A size the theme fixes at a length, such as a 12px supporting size, scales on the curve of the step it reads by default; a size in `em` or `%` follows its parent, and one that reads a variable follows that variable. At the default size every font size is the theme's own. The family, spacing, radius and the root font size never change, line heights keep their ratios, text inputs keep their 16px floor on iOS, and browsers without the keyword see no change. There is nothing to turn on: no theme option, prop or document attribute.",
+        },
+        {
+          type: 'prose',
+          text: 'Fixed-height controls such as the text inputs keep their height, so their text can overflow at the accessibility sizes. A labelled `Button` grows with its label.',
+        },
+      ],
+    },
   ],
 };

package/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.tsx

@@ -74,6 +74,7 @@ function CouponField({statusVariant}: {statusVariant: FieldStatusPlacement}) {
       <div
         {...stylex.props(
           inputWrapperStyles.base,
+          inputWrapperStyles.textField,
           styles.field,
           status && inputStatusBorderStyles[status.type],
         )}>

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

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableRowsVirtualization',
+  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.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

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

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  Table,
+  useTableRowsVirtualization,
+  type TableColumn,
+} from '@astryxdesign/core/Table';
+
+interface Product extends Record<string, unknown> {
+  id: string;
+  name: string;
+}
+
+const products: Product[] = Array.from({length: 1000}, (_, index) => ({
+  id: `product-${index}`,
+  name: `Product ${index + 1}`,
+}));
+const columns: TableColumn<Product>[] = [{key: 'name', header: 'Product'}];
+
+export default function RowsVirtualizationHookUsage() {
+  const virtualization = useTableRowsVirtualization({
+    rowHeight: 56,
+    viewportHeight: 320,
+  });
+  return (
+    <Table
+      data={products}
+      columns={columns}
+      idKey="id"
+      virtualization={virtualization}
+    />
+  );
+}

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

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableColumnSettingsState',
+  name: 'useTableColumnSettingsState — Column Visibility Picker',
+  displayName: 'useTableColumnSettingsState — Column Visibility Picker',
+  description:
+    'A Table toolbar with a Columns menu of checkboxes: toggling Email updates active columns, Reset restores defaults, and the config is passed directly to useTableColumnSettings.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Button', 'CheckboxInput', 'Popover', 'Table', 'Layout'],
+};

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

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Popover} from '@astryxdesign/core/Popover';
+import {
+  Table,
+  useTableColumnSettings,
+  useTableColumnSettingsState,
+} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+interface Member extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const members: Member[] = [
+  {id: '1', name: 'Alice', email: 'alice@example.com', role: 'Engineer'},
+  {id: '2', name: 'Bob', email: 'bob@example.com', role: 'Designer'},
+  {id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'Manager'},
+];
+
+const allColumns: TableColumn<Member>[] = [
+  {key: 'name', header: 'Name'},
+  {key: 'email', header: 'Email'},
+  {key: 'role', header: 'Role'},
+];
+
+const columnOptions = [
+  {key: 'name' as const, label: 'Name', isAlwaysVisible: true},
+  {key: 'email' as const, label: 'Email'},
+  {key: 'role' as const, label: 'Role'},
+];
+
+const defaultKeys = ['name', 'email', 'role'];
+
+export default function UseTableColumnSettingsStateHookUsage() {
+  const [activeKeys, setActiveKeys] =
+    useState<ReadonlyArray<string>>(defaultKeys);
+
+  const state = useTableColumnSettingsState({
+    columns: columnOptions,
+    activeColumnKeys: activeKeys,
+    onChangeActiveColumnKeys: setActiveKeys,
+    defaultColumnKeys: defaultKeys,
+  });
+
+  const plugin = useTableColumnSettings<Member>(state.columnSettingsConfig);
+
+  return (
+    <VStack gap={3}>
+      <HStack hAlign="start">
+        <Popover
+          placement="below"
+          label="Column settings"
+          width={200}
+          content={
+            <VStack gap={2}>
+              {columnOptions.map(col => (
+                <CheckboxInput
+                  key={col.key}
+                  label={col.label}
+                  value={state.isColumnActive(col.key)}
+                  isDisabled={!state.isColumnToggleable(col.key)}
+                  onChange={() => state.toggleColumn(col.key)}
+                />
+              ))}
+              <Button
+                label="Reset"
+                size="sm"
+                variant="secondary"
+                onClick={state.resetToDefault}>
+                Reset
+              </Button>
+            </VStack>
+          }>
+          <Button label="Columns" size="sm">
+            Columns
+          </Button>
+        </Popover>
+      </HStack>
+      <Table
+        data={members}
+        columns={allColumns}
+        idKey="id"
+        plugins={{columnSettings: plugin}}
+      />
+    </VStack>
+  );
+}

package/assets/templates/pages/table-filter/page.tsx

@@ -1129,18 +1129,6 @@ const INITIAL_SAVED_VIEWS: SavedView[] = [
 const COMPACT_SURFACE_QUERY =
   '(max-width: 768px), (max-width: 1024px) and (pointer: coarse) and (hover: none)';
 
-/**
- * Top padding for whatever opens a BottomSheet, on the spacing scale.
- *
- * The panel's grab pill floats over the content instead of reserving layout
- * space for itself: it is 4px centered in a 24px band, so it covers the top
- * 10-14px of the sheet. Content that starts at the usual 16px gutter clears it
- * by 2px, which does not read as a gap — it reads as the sheet being cut off.
- * Opening at the full 24px band puts real space under the pill, and every
- * sheet here uses this one value so they all start on the same line.
- */
-const SHEET_TOP_INSET = 6;
-
 /**
  * Width the filter row holds back, in px, for the readout that trails the
  * clauses — the density toggle, the result count and Clear all.
@@ -1698,6 +1686,7 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-body-size'],
     fontWeight: typeScaleVars['--text-body-weight'],
     height: 'auto',
+    minHeight: 0,
     lineHeight: typeScaleVars['--text-body-leading'],
     paddingBlock: 0,
     paddingInline: 0,
@@ -2052,7 +2041,8 @@ function FilterOverflow({
     <VStack
       gap={2}
       padding={isCompactSurface ? 4 : 0}
-      paddingBlockStart={isCompactSurface ? SHEET_TOP_INSET : 0}>
+      // In a sheet the sheet's band under its grab bar is the top inset.
+      paddingBlockStart={0}>
       {items.map(({child, index}) => (
         <StackItem key={index} xstyle={styles.overflowItem}>
           {child}
@@ -2145,7 +2135,8 @@ function AdaptiveSavedViewForm({
         <Section
           variant="transparent"
           padding={4}
-          paddingBlockStart={SHEET_TOP_INSET}>
+          // The sheet's band under its grab bar is the top inset.
+          paddingBlockStart={0}>
           <VStack gap={4}>
             <HStack gap={2}>
               <StackItem size="fill">
@@ -4090,11 +4081,11 @@ export default function TableFilterTemplate() {
       label="View options"
       height="tall"
       // The tab strip compensates against a container inset, so the sheet
-      // publishes none and the wrapper below owns the top band.
+      // publishes none; its band under the grab bar is the only top inset,
+      // so the strip's own box starts at the tab row and its scroll arrow
+      // lands on the tabs rather than above them.
       padding={0}>
-      {/* The inset is the wrapper's, so the strip's own box starts at the tab
-          row and its scroll arrow lands on the tabs rather than above them. */}
-      <VStack gap={0} paddingBlockStart={SHEET_TOP_INSET}>
+      <VStack gap={0}>
         {/* The heading the popover puts above the pane is dropped here: it
             restates the selected tab word for word, and the strip already
             marks which one that is. On a phone that is a line of vertical
@@ -4148,14 +4139,15 @@ export default function TableFilterTemplate() {
   const detailBody =
     activeJob == null ? null : (
       <VStack gap={0} xstyle={styles.detailPanel}>
-        {/* The only part of the body that knows which host it is in: the sheet
-            needs the pill cleared, the docked panel has no pill and would just
-            sit 8px lower than the panels beside it. The two never coexist —
-            Layout drops the panel entirely on a compact surface. */}
+        {/* The only part of the body that knows which host it is in: in the
+            sheet, the sheet's band under its grab bar is the top inset; the
+            docked panel has no pill and keeps the 16px gutter of the panels
+            beside it. The two never coexist — Layout drops the panel entirely
+            on a compact surface. */}
         <Section
           variant="transparent"
           padding={4}
-          paddingBlockStart={isCompactSurface ? SHEET_TOP_INSET : 4}>
+          paddingBlockStart={isCompactSurface ? 0 : 4}>
           <VStack gap={4}>
             <HStack gap={2}>
               <StackItem size="fill">

package/assets/templates/pages/table-inbox/page.tsx

@@ -1785,12 +1785,9 @@ function ComposeWindow({
       hasScrim={false}
       // The Layout below owns the inset; the sheet adds none of its own.
       padding={0}>
-      {/* The grab handle floats over the top edge, out of flow, about 12px
-          down. The Layout's own padding is not quite enough to clear it — the
-          heading came up level with the pill, four pixels under it — so the
-          sheet buys the handle its own band of space before the content
-          starts. */}
-      <VStack paddingBlockStart={3}>
+      {/* The sheet keeps a band under its grab handle at rest, so the Layout
+          starts below the pill without a band of its own. */}
+      <VStack>
         <Layout
           // auto, not fill: the sheet is sized by this Layout now rather than
           // the other way round. `fill` would stretch it to a height that

package/assets/templates/themes/butter/butterTheme.ts

@@ -394,8 +394,8 @@ export const butterTheme = defineTheme({
       // Radius intentionally not pinned, so buttons keep core's
       // `var(--_button-radius, --radius-element)`: standalone buttons stay 8px,
       // while the chat composer (which sets --_button-radius) rounds them fully.
+      // Inline padding only. Button sets its own block padding and height.
       base: {
-        paddingBlock: 'var(--spacing-3)',
         paddingInline: 'var(--spacing-4)',
       },
       'variant:secondary': SECONDARY_BUTTON,

package/foundation/discovery/hook-discovery.mjs

@@ -12,6 +12,13 @@ import {levenshteinDistance} from '../text/string-utils.mjs';
 
 const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
 
+// A hook's doc outside src/hooks/: a `use…` hook, or a `create…` factory
+// documented as one (its doc typed `HookDoc`, such as createReorderable).
+const HOOK_DOC_FILE_RE = /^(?:use|create)[A-Z]\w*\.doc\.mjs$/;
+
+// Matches the top-level `relatedHooks: [...]` field in a hook .doc.mjs file.
+const RELATED_HOOKS_RE = /(?:^|\n) {0,4}relatedHooks:\s*\[([^\]]*)\]/;
+
 // Matches the top-level `category: 'categoryName'` field in a hook .doc.mjs file.
 const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
 
@@ -32,6 +39,25 @@ function readHookMeta(docPath) {
   }
 }
 
+/**
+ * Whether a `create…` factory's doc names its own `use…` hook in
+ * `relatedHooks`, as createAnimator's names useAnimator. Such a factory is
+ * listed beside that hook, not on its own.
+ * @param {string} docPath
+ * @param {string} hookName
+ * @returns {boolean}
+ */
+function isBesideOwnHook(docPath, hookName) {
+  if (!hookName.startsWith('create')) return false;
+  const ownHook = `use${hookName.slice('create'.length)}`;
+  try {
+    const related = RELATED_HOOKS_RE.exec(fs.readFileSync(docPath, 'utf-8'));
+    return related != null && related[1].includes(`'${ownHook}'`);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Extract the hook name from a doc filename.
  * e.g. 'useFocusTrap.doc.mjs' → 'useFocusTrap'
@@ -70,7 +96,8 @@ export function discoverHooks(coreDir) {
     }
   }
 
-  // 2. Scan ALL component directories for files matching use*.doc.mjs
+  // 2. Scan ALL component directories for hook docs: use*.doc.mjs, and
+  // create*.doc.mjs for a factory documented as a hook (createReorderable)
   if (pathExists(srcDir)) {
     const topEntries = listDirEntries(srcDir);
     for (const entry of topEntries) {
@@ -120,14 +147,10 @@ function scanDirForHookDocs(dirPath, hookCategories) {
   for (const entry of entries) {
     if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
       scanDirForHookDocs(path.join(dirPath, entry.name), hookCategories);
-    } else if (
-      entry.isFile() &&
-      entry.name.startsWith('use') &&
-      entry.name.endsWith('.doc.mjs')
-    ) {
+    } else if (entry.isFile() && HOOK_DOC_FILE_RE.test(entry.name)) {
       const hookName = hookNameFromFile(entry.name);
-      if (!hookCategories.has(hookName)) {
-        const docPath = path.join(dirPath, entry.name);
+      const docPath = path.join(dirPath, entry.name);
+      if (!hookCategories.has(hookName) && !isBesideOwnHook(docPath, hookName)) {
         const {category} = readHookMeta(docPath);
         hookCategories.set(hookName, category || 'Other');
       }

package/foundation/text/levenshtein.d.mts

@@ -19,6 +19,11 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a: string, b: string, max?: number): number;
+export function levenshteinDistance(a: string, b: string, max?: number, { swaps }?: {
+    swaps?: boolean;
+}): number;

package/foundation/text/levenshtein.mjs

@@ -19,11 +19,15 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a, b, max) {
-  if (max !== undefined) return distanceWithin(a, b, max);
-  const m = a.length, n = b.length;
+export function levenshteinDistance(a, b, max, {swaps = false} = {}) {
+  if (max !== undefined) return distanceWithin(a, b, max, swaps);
+  const m = a.length,
+    n = b.length;
   // Early exit: the distance is always ≥ |m − n|, so once the length gap
   // exceeds the loosest fuzzy-match threshold any caller uses (the hook
   // suggester keeps distance ≤ 5) the pair can never match — skip the O(m·n)
@@ -36,9 +40,10 @@ export function levenshteinDistance(a, b, max) {
   for (let j = 0; j <= n; j++) dp[0][j] = j;
   for (let i = 1; i <= m; i++) {
     for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i-1] === b[j-1]
-        ? dp[i-1][j-1]
-        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
     }
   }
   return dp[m][n];
@@ -51,11 +56,13 @@ export function levenshteinDistance(a, b, max) {
  * @param {string} a
  * @param {string} b
  * @param {number} max
+ * @param {boolean} swaps - two adjacent letters swapped cost one edit
  * @returns {number}
  */
-function distanceWithin(a, b, max) {
+function distanceWithin(a, b, max, swaps) {
   const over = max + 1;
   if (Math.abs(a.length - b.length) > max) return over;
+  let before = new Array(b.length + 1).fill(over);
   let previous = new Array(b.length + 1).fill(over);
   let current = new Array(b.length + 1).fill(over);
   for (let j = 0; j <= Math.min(b.length, max); j++) previous[j] = j;
@@ -67,18 +74,27 @@ function distanceWithin(a, b, max) {
     let rowMin = current[0];
     for (let j = from; j <= to; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const value = Math.min(
+      let value = Math.min(
         previous[j - 1] + cost,
         previous[j] + 1,
         current[j - 1] + 1,
         over,
       );
+      if (
+        swaps &&
+        i > 1 &&
+        j > 1 &&
+        a[i - 1] === b[j - 2] &&
+        a[i - 2] === b[j - 1]
+      ) {
+        value = Math.min(value, before[j - 2] + 1);
+      }
       current[j] = value;
       if (value < rowMin) rowMin = value;
     }
     // Every later cell costs at least this row's least.
     if (rowMin >= over) return over;
-    [previous, current] = [current, previous];
+    [before, previous, current] = [previous, current, before];
   }
   return Math.min(previous[b.length], over);
 }

package/foundation/text/suggest-order.d.mts

@@ -18,15 +18,22 @@ export function nameWords(text: string): string[];
  * when it carries some of them, the items that carry none are left out. When
  * no item carries one, nothing is left out. The list only ever gets shorter,
  * and its order does not change.
+ *
+ * With `typos`, a near name (one or two slips from the typed name, as
+ * `ButonGroup` or `ButtonGorup` for ButtonGroup) ranks just below the names
+ * that carry every typed word and above the rest. With `closest` too, near
+ * names stay in the list whatever the cut leaves out, and the list is never
+ * longer than it is without `typos`.
  * @template T
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
- * @param {{closest?: boolean}} [options]
+ * @param {{closest?: boolean, typos?: boolean}} [options]
  * @returns {T[]}
  */
 export function orderByAffinity<T>(typedName: string, items: T[], namesOf: (item: T) => Array<string | undefined>, options?: {
     closest?: boolean;
+    typos?: boolean;
 }): T[];
 /**
  * Docs route suggestions, closest to the typed route first. When every

package/foundation/text/suggest-order.mjs

@@ -19,6 +19,12 @@
 
 import {levenshteinDistance} from './levenshtein.mjs';
 
+/**
+ * The score of a near name (nearNameSlips), less a little per slip: above any
+ * name that carries only some of the typed words, below one that carries all
+ * of them.
+ */
+const NEAR_NAME_SCORE = 19.6;
 /** The score a synonym match gets: an exact keyword's. */
 const SYNONYM_SCORE = 90;
 /** The score a name with exactly the typed words gets: an exact name's. */
@@ -59,17 +65,22 @@ export function nameWords(text) {
  * closer. Tiers, best first: the same words; every typed word present; some
  * typed word present; none. Within a tier, more of the typed words and more of
  * the candidate's own words matched rank higher, and a name that starts with
- * the typed name (or the reverse) gets a small lift.
+ * the typed name (or the reverse) gets a small lift. With `typos`, a near name
+ * (one or two slips from the typed name) ranks just below the names that
+ * carry every typed word.
  * @param {string[]} typed - {@link nameWords} of the typed name
  * @param {string} name
+ * @param {{typos?: boolean}} [options]
  * @returns {number}
  */
-function affinityOf(typed, name) {
+function affinityOf(typed, name, {typos = false} = {}) {
   const words = nameWords(name);
   if (typed.length === 0 || words.length === 0) return 0;
   const typedJoined = typed.join('');
   const joined = words.join('');
   if (joined === typedJoined) return 40;
+  const slips = typos ? nearNameSlips(typedJoined, joined) : 0;
+  const near = slips > 0 ? NEAR_NAME_SCORE - slips * 0.2 : 0;
   const have = new Set(words);
   const want = new Set(typed);
   const covered = typed.filter(w => have.has(w)).length / typed.length;
@@ -77,7 +88,29 @@ function affinityOf(typed, name) {
   const prefix =
     joined.startsWith(typedJoined) || typedJoined.startsWith(joined) ? 1 : 0;
   const tier = covered === 1 ? 2 : covered > 0 ? 1 : 0;
-  return tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01;
+  // A near name keeps its word score when that is higher: a name that also
+  // carries every typed word ranks among the other full matches.
+  return Math.max(
+    near,
+    tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01,
+  );
+}
+
+/**
+ * How many slips separate a typed name from a candidate, both with their
+ * words joined, when it is a near name: an edit or two adjacent letters
+ * swapped count as one slip, one slip is allowed from five letters and two from
+ * eight. Zero when it is not a near name.
+ * @param {string} typed
+ * @param {string} name
+ * @returns {number}
+ */
+function nearNameSlips(typed, name) {
+  const shorter = Math.min(typed.length, name.length);
+  const cap = shorter >= 8 ? 2 : shorter >= 5 ? 1 : 0;
+  if (cap === 0 || Math.abs(typed.length - name.length) > cap) return 0;
+  const slips = levenshteinDistance(typed, name, cap, {swaps: true});
+  return slips <= cap ? slips : 0;
 }
 
 /**
@@ -87,14 +120,15 @@ function affinityOf(typed, name) {
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{typos?: boolean}} [options]
  * @returns {Array<{item: T, best: number}>}
  */
-function scoreByAffinity(typedName, items, namesOf) {
+function scoreByAffinity(typedName, items, namesOf, options = {}) {
   const typed = nameWords(typedName);
   const scored = items.map((item, index) => {
     let best = 0;
     for (const name of namesOf(item)) {
-      if (name) best = Math.max(best, affinityOf(typed, name));
+      if (name) best = Math.max(best, affinityOf(typed, name, options));
     }
     return {item, index, best};
   });
@@ -112,14 +146,46 @@ function scoreByAffinity(typedName, items, namesOf) {
  * when it carries some of them, the items that carry none are left out. When
  * no item carries one, nothing is left out. The list only ever gets shorter,
  * and its order does not change.
+ *
+ * With `typos`, a near name (one or two slips from the typed name, as
+ * `ButonGroup` or `ButtonGorup` for ButtonGroup) ranks just below the names
+ * that carry every typed word and above the rest. With `closest` too, near
+ * names stay in the list whatever the cut leaves out, and the list is never
+ * longer than it is without `typos`.
  * @template T
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
- * @param {{closest?: boolean}} [options]
+ * @param {{closest?: boolean, typos?: boolean}} [options]
  * @returns {T[]}
  */
 export function orderByAffinity(typedName, items, namesOf, options = {}) {
+  if (!options.typos) return orderByWords(typedName, items, namesOf, options);
+  const scored = scoreByAffinity(typedName, items, namesOf, {typos: true});
+  if (!options.closest) return scored.map(s => s.item);
+  const kept = new Set(orderByWords(typedName, items, namesOf, options));
+  return scored
+    .filter(s => kept.has(s.item) || isNearScore(s.best))
+    .slice(0, kept.size)
+    .map(s => s.item);
+}
+
+/**
+ * Whether a score is a near name's.
+ * @param {number} score
+ */
+const isNearScore = score => score < 20 && score > NEAR_NAME_SCORE - 1;
+
+/**
+ * {@link orderByAffinity} without `typos`.
+ * @template T
+ * @param {string} typedName
+ * @param {T[]} items
+ * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{closest?: boolean}} options
+ * @returns {T[]}
+ */
+function orderByWords(typedName, items, namesOf, options) {
   const scored = scoreByAffinity(typedName, items, namesOf);
   if (!options.closest) return scored.map(s => s.item);
   // One-letter words (`a` in `a11y`, `use-a-theme`) say nothing about which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.c73b9e4",
+  "version": "0.7.12-canary.c86484d",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -125,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.12-canary.c73b9e4"
+    "@astryxdesign/core": "0.7.12-canary.c86484d"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -133,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.c73b9e4",
-    "@astryxdesign/core": "0.7.12-canary.c73b9e4",
-    "@astryxdesign/lab": "0.7.12-canary.c73b9e4",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.c73b9e4",
+    "@astryxdesign/charts": "0.7.12-canary.c86484d",
+    "@astryxdesign/core": "0.7.12-canary.c86484d",
+    "@astryxdesign/lab": "0.7.12-canary.c86484d",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.c86484d",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",