Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): search finds compound names typed as words, other libraries' names, and verb forms (#7718)

Joey493231799229
diff --git a/.changeset/search-compound-names.md b/.changeset/search-compound-names.md
new file mode 100644
index 0000000000..56ae8e815d
--- /dev/null
+++ b/.changeset/search-compound-names.md
@@ -0,0 +1,15 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[fix] `astryx search` finds more of what a reader means when the words differ from the catalog's.
+
+@josephfarina
+
+- Adjacent query words that join into a component, hook, or template name, or into a one-word keyword, match it: `table header cell with sort arrow` finds `TableHeaderCell`, `tree view folders` the `treeview` keyword, and a hook answers to its words without `use`. Most of a name, a name's leading words, or a run of its words also count for components and hooks, a step below the full name.
+- A query that is one camelCase identifier and matches nothing as typed is read as the words it spells, so an unknown API name such as `useTablePaginationState` reaches `useTablePagination`. In a query of several words each identifier stays one term.
+- When the whole query is an entry's name, these readings add no near siblings beside it. A match on part of another name or on a joined keyword never ranks above an entry the query names.
+- A gerund matches its verb (`spacing` and `space`, `dragging` and `drag`), and a plural can start a longer word through its singular (`tokens` and `Tokenizer`).
+- Core component docs declare more keywords: other libraries' names (`scrollarea`, `togglegroup`, `pageheader`, `splitpane`, `circularprogress`, `linearprogress`, `commandmenu`, `relativetime`, `sidesheet`, `descriptionlist`, `inlinecode`) and common glyph names on `Icon`, since any icon library's glyph renders through it.
+- The JSON shape is unchanged.
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index fad501161d..bc78cbf7dc 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -259,9 +259,34 @@ function wordForms(w) {
if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+ // A gerund keeps its verb: "spacing" lost a final e ("space"), and
+ // "dragging" doubled a consonant ("drag"). A past participle does not: it
+ // usually describes a state ("archived notes"), not the action a catalog
+ // word names.
+ if (w.length >= 6 && w.endsWith('ing')) {
+ const base = w.slice(0, -3);
+ forms.add(base);
+ forms.add(`${base}e`);
+ if (/([b-df-hj-np-tv-z])\1$/.test(base)) forms.add(base.slice(0, -1));
+ }
return forms;
}
+/**
+ * The singulars a lowercase word may have when it ends in a plural suffix:
+ * "tokens" is "token", "boxes" is "box", "entries" is "entry".
+ * @param {string} w
+ * @returns {string[]}
+ */
+function singulars(w) {
+ /** @type {string[]} */
+ const out = [];
+ if (w.length > 3 && w.endsWith('s')) out.push(w.slice(0, -1));
+ if (w.length > 4 && w.endsWith('es')) out.push(w.slice(0, -2));
+ if (w.length > 4 && w.endsWith('ies')) out.push(w.slice(0, -3) + 'y');
+ return out;
+}
+
/**
* Whether two lowercase words are the same word, up to plural and stem form.
* @param {string} a
@@ -302,9 +327,180 @@ function wordsOf(text) {
function startsAWordOf(term, text) {
if (term.length < 4) return false;
if (term.length / String(text).length < 0.5) return false;
- return wordsOf(text).some(w => w.startsWith(term) || sameWord(term, w));
+ // The term or its singular may start the word: "tokens" starts
+ // "tokenizer" through "token". A singular needs five letters, so "stats"
+ // does not start "status".
+ const starts = [term, ...singulars(term).filter(f => f.length >= 5)];
+ return wordsOf(text).some(
+ w => starts.some(f => w.startsWith(f)) || sameWord(term, w),
+ );
+}
+
+/**
+ * A query with its camelCase and PascalCase identifiers spelled as words, so
+ * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
+ * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
+ * unchanged: a joined token that matches nothing stays unmatched.
+ * @param {string} query - The query as typed, before lowercasing.
+ * @returns {string} Lowercased.
+ */
+export function spellIdentifiers(query) {
+ return String(query)
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+ .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+ .toLowerCase();
+}
+
+/**
+ * A name or keyword with its separators removed, lowercased: `Side Nav`,
+ * `side-nav`, and `SideNav` all join to `sidenav`.
+ * @param {string} text
+ * @returns {string}
+ */
+function joined(text) {
+ return String(text)
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '');
+}
+
+/**
+ * The strongest hit a run of two or more adjacent query words has when it is
+ * read as one joined word, and the query words it covers. Readers type a
+ * compound name as separate words (`table header cell` is TableHeaderCell,
+ * `number field` the keyword `numberfield`), and no single word of the run
+ * matches on its own.
+ *
+ * - 100: the run joins to a component, hook, or template name, or its plural
+ * (`table header cells` is TableHeaderCell), or a hook name without its
+ * `use` prefix (`table sticky columns` is useTableStickyColumns).
+ * - 90: the run joins to a one-word keyword (`number field` is
+ * `numberfield`).
+ * - 95: the run joins to most of a name, cut short (`dropdown menu radio` is
+ * DropdownMenuRadioItem); 92: it is a name's leading words, covering at least half
+ * of it (`top nav mega` is TopNavMegaMenu); 70: it is two or more adjacent
+ * words of a name that cover at least half of it (`header cell` in
+ * TableHeaderCell), the same coverage a word prefix needs. These three
+ * are for components and hooks only.
+ *
+ * A doc's name is a route or key, so docs are left out.
+ * @param {string[]} words - The query's words, stopwords included.
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string, covered: Set<string>, alias?: boolean} | null}
+ * `covered` holds the run's words and every stretch of them joined. `alias`
+ * marks a hit on part of a name or on a keyword, not on the whole name.
+ */
+export function compoundHit(words, candidate) {
+ if (candidate.domain === 'doc' || words.length < 2) return null;
+ const names = [candidate.name, ...(candidate.aliases ?? [])]
+ .filter(Boolean)
+ .map(name => ({name, nameJoined: joined(name), nameWords: wordsOf(name)}));
+ // Part of a name counts only for a component or hook. A template's name
+ // starts with the component it shows (`ProgressBarShowcase`), so part of it
+ // names the component, not the template.
+ const partial =
+ candidate.domain === 'component' || candidate.domain === 'hook';
+ // One-word lowercase keywords: a keyword an author declares for a reader
+ // to type, joined (`numberfield`). A capitalized one names another entry (a
+ // block's `componentsUsed`), which matches by its own name, and a keyword of
+ // several words is a phrase, matched as one.
+ const keywords = (candidate.keywords ?? []).filter(k =>
+ /^[a-z0-9]+$/.test(String(k)),
+ );
+ /** @type {{score: number, reason: string, covered: Set<string>, alias?: boolean} | null} */
+ let best = null;
+ for (const {run, word} of queryRuns(words)) {
+ let score = 0;
+ let reason = '';
+ for (const {name, nameJoined, nameWords} of names) {
+ if (
+ nameJoined === word ||
+ pluralOf(word, nameJoined) ||
+ (candidate.domain === 'hook' && nameJoined === `use${word}`)
+ ) {
+ if (score < 100) [score, reason] = [100, `name ${name} spelled`];
+ } else if (!partial) {
+ continue;
+ } else if (
+ nameJoined.startsWith(word) &&
+ word.length / nameJoined.length >= 0.75
+ ) {
+ // Most of the name, cut short: `dropdown menu radio` is
+ // DropdownMenuRadioItem.
+ if (score < 95) [score, reason] = [95, `name ${name} spelled`];
+ } else if (
+ word.length / nameJoined.length >= 0.5 &&
+ run.every(
+ (w, j) => nameWords[j + (nameWords[0] === 'use' ? 1 : 0)] === w,
+ )
+ ) {
+ // The name's leading words: `top nav mega` is TopNavMegaMenu.
+ if (score < 92)
+ [score, reason] = [92, `name ${name} starts "${run.join(' ')}"`];
+ } else if (
+ word.length / nameJoined.length >= 0.5 &&
+ nameWords.some((_, k) => run.every((w, j) => nameWords[k + j] === w))
+ ) {
+ if (score < 70)
+ [score, reason] = [70, `name ${name} holds "${run.join(' ')}"`];
+ }
+ }
+ if (score < 90 && keywords.includes(word)) {
+ [score, reason] = [90, `keyword "${run.join(' ')}" spelled`];
+ }
+ if (score > (best?.score ?? 0)) {
+ // Each word of the run, and each identifier typed as several of its
+ // words joined (`dropdownMenu` in `dropdownMenu checkbox`).
+ const covered = new Set();
+ for (let a = 0; a < run.length; a++) {
+ for (let b = a + 1; b <= run.length; b++) {
+ covered.add(run.slice(a, b).join(''));
+ }
+ }
+ best = {score, reason, covered, ...(score < 100 ? {alias: true} : {})};
+ }
+ }
+ return best;
+}
+
+/**
+ * The longest run of adjacent query words read as one name. Core's longest
+ * names run to six words; a longer run is a sentence, not a name, and reading
+ * every run of a long build idea costs time on every candidate.
+ */
+const MAX_RUN_WORDS = 6;
+
+/**
+ * Each run of two to {@link MAX_RUN_WORDS} adjacent query words, longest
+ * first, with the run joined into one word. Computed once per query.
+ * @type {WeakMap<string[], {run: string[], word: string}[]>}
+ */
+const runsOf = new WeakMap();
+
+/**
+ * @param {string[]} words
+ * @returns {{run: string[], word: string}[]}
+ */
+function queryRuns(words) {
+ let runs = runsOf.get(words);
+ if (runs) return runs;
+ runs = [];
+ for (let len = Math.min(words.length, MAX_RUN_WORDS); len >= 2; len--) {
+ for (let i = 0; i + len <= words.length; i++) {
+ const run = words.slice(i, i + len);
+ runs.push({run, word: run.join('')});
+ }
+ }
+ runsOf.set(words, runs);
+ return runs;
}
+/**
+ * Each candidate's compound hit from its last scoreQuery, so domainPriority
+ * reads it without walking the query's runs again.
+ * @type {WeakMap<object, ReturnType<typeof compoundHit>>}
+ */
+const compoundOf = new WeakMap();
+
/**
* The fewest letters both words need before an edit distance counts as a
* typo, by distance. Below them, one edit usually makes a different word.
@@ -541,7 +737,13 @@ const STRONG_TOKEN_SCORE = 70;
* candidate's scoreQuery result.
* @returns {0 | 1 | 2}
*/
-export function domainPriority(term, tokens, candidate, hit) {
+export function domainPriority(
+ term,
+ tokens,
+ candidate,
+ hit,
+ queryWords = phraseWords(term),
+) {
const words = [term, ...tokens];
if (candidate.domain === 'doc') {
const topic = String(candidate._topic ?? candidate.name).toLowerCase();
@@ -600,6 +802,12 @@ export function domainPriority(term, tokens, candidate, hit) {
return 0;
}
if (hit.score >= FULL_COVERAGE_SCORE) return 1;
+ const compound = compoundOf.has(candidate)
+ ? compoundOf.get(candidate)
+ : compoundHit(queryWords, candidate);
+ if ((compound?.score ?? 0) >= STRONG_TOKEN_SCORE) {
+ return 1;
+ }
const fuzzy = tokens.length <= 1;
return words.some(
w =>
@@ -715,14 +923,24 @@ export function titleInQuery(term, titles) {
* @param {string} term - Lowercased full query.
* @param {string[]} tokens - Content tokens from tokenizeQuery(term).
* @param {Candidate} candidate
- * @returns {{score: number, reason: string, matched: number, total: number} | null}
+ * @param {string[]} [words] - The query's words for compound names (see
+ * compoundHit); empty when the query names an entry outright.
+ * @param {{plain?: boolean}} [opts] - `plain`: score without matches on part
+ * of a name or a joined keyword.
+ * @returns {{score: number, reason: string, matched: number, total: number, alias?: boolean} | null}
* `matched`/`total` are the query concepts this candidate answered, out of
* the concepts the query had. Callers that must distinguish "matched one word
* of three" from "matched all three" — `build`, which gates its pages group
* on coverage — cannot recover that from the score, because a single strong
* hit and a broad weak one land on the same number.
*/
-export function scoreQuery(term, tokens, candidate) {
+export function scoreQuery(
+ term,
+ tokens,
+ candidate,
+ words = phraseWords(term),
+ {plain = false} = {},
+) {
const total = Math.max(tokens.length, 1);
// A whole-phrase hit answered the whole query by definition.
const asFull = (/** @type {{score: number, reason: string}} */ hit) => ({
@@ -731,14 +949,24 @@ export function scoreQuery(term, tokens, candidate) {
total,
});
// Typo tolerance is for one-word lookups. In a multi-word query a near miss
- // is usually a different word, not a typo.
- const fuzzy = tokens.length <= 1;
- const full = scoreCandidate(term, candidate, {fuzzy});
+ // is usually a different word, not a typo. One typed identifier is one
+ // word, whatever words it spells.
+ const fuzzy = tokens.length <= 1 || !/\s/.test(term);
+ const full = scoreCandidate(term, candidate, {
+ fuzzy,
+ joins: !plain && words.length > 0,
+ });
// A query of several words keeps its phrase tiers below even when stopwords
// leave one content word: "make an integration" is still the phrase an
// author declares as a keyword, and "build an integration" still names a
// title outright, though each tokenizes to `integration` alone.
- const phrase = phraseWords(term).length >= 2;
+ const phrase = phraseWords(term).length >= 2 || words.length >= 2;
+ let compound = compoundHit(words, candidate);
+ if (plain) {
+ if (compound?.alias) compound = null;
+ } else {
+ compoundOf.set(candidate, compound);
+ }
/** 0–1 content tokens: whole-phrase fuzzy matching (typo tolerance for
* single words), but if stopwords left exactly one DIFFERENT token (e.g.
@@ -763,7 +991,11 @@ export function scoreQuery(term, tokens, candidate) {
// of Table-related templates each match "table" and "contents" separately
// and accumulate a higher raw score (#5239).
if (full && full.score >= 90) {
- return asFull({score: full.score + 100, reason: full.reason});
+ return asFull({
+ score: full.score + 100,
+ reason: full.reason,
+ ...(full.alias ? {alias: true} : {}),
+ });
}
// The whole query standing as a phrase in a doc's title or one of its
@@ -789,8 +1021,20 @@ export function scoreQuery(term, tokens, candidate) {
let tokenSum = 0;
/** @type {string[]} */
const hitTerms = [];
+ // Adjacent words that join into a name or keyword answer each word they
+ // join, as strongly as the joined word matches (see compoundHit).
+ // Whether a counted word matched only through part of a name or a keyword
+ // read joined, not through the entry's own name or a word of it.
+ let alias = false;
for (const tok of tokens) {
- const h = bestForToken(tok, candidate, {fuzzy});
+ let h = bestForToken(tok, candidate, {fuzzy});
+ if (
+ compound?.covered.has(joined(tok)) &&
+ compound.score > (h?.score ?? 0)
+ ) {
+ h = compound;
+ if (compound.alias && compound.score >= MIN_TOKEN_SCORE) alias = true;
+ }
if (h && h.score >= MIN_TOKEN_SCORE) {
if (h.score > strongest) strongest = h.score;
matched++;
@@ -840,6 +1084,7 @@ export function scoreQuery(term, tokens, candidate) {
reason,
matched,
total,
+ ...(alias ? {alias} : {}),
};
}
@@ -865,7 +1110,7 @@ export function scoreQuery(term, tokens, candidate) {
strongest + Math.min(matched - 1, 3) * 12 + coverage * 15,
);
if (full && full.score >= tokenScore) return asFull(full);
- return {score: tokenScore, reason, matched, total};
+ return {score: tokenScore, reason, matched, total, ...(alias ? {alias} : {})};
}
/**
@@ -884,8 +1129,9 @@ export function scoreQuery(term, tokens, candidate) {
* @param {string} [candidate.description]
* @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
* @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
- * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
- * @returns {{score: number, reason: string} | null}
+ * @param {{fuzzy?: boolean, joins?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false. `joins`: read a spaced query joined into a name or keyword (default true); off when the query names an entry outright.
+ * @returns {{score: number, reason: string, alias?: boolean} | null} `alias`
+ * marks a hit that read the query's words joined.
*/
export function scoreCandidate(
term,
@@ -899,18 +1145,21 @@ export function scoreCandidate(
prose = [],
guidance = [],
},
- {fuzzy = true} = {},
+ {fuzzy = true, joins = true} = {},
) {
let best = 0;
let reason = '';
+ let alias = false;
/**
* @param {number} score
* @param {string} why
+ * @param {boolean} [byAlias] - the hit reads the query's words joined
*/
- const consider = (score, why) => {
+ const consider = (score, why, byAlias = false) => {
if (score > best) {
best = score;
reason = why;
+ alias = byAlias;
}
};
@@ -934,6 +1183,16 @@ export function scoreCandidate(
nameLower === term.replace(/\s+/g, '');
if (nameLower === term || leafLower === term || spelled) {
consider(100, 'exact name');
+ } else if (
+ joins &&
+ (domain === 'component' || domain === 'hook') &&
+ /\s/.test(term) &&
+ nameLower.startsWith(term.replace(/\s+/g, '')) &&
+ term.replace(/\s+/g, '').length / nameLower.length >= 0.75
+ ) {
+ // Most of the name typed as words, cut short: `complex select` is
+ // ComplexSelector, ahead of a one-word keyword elsewhere.
+ consider(95, `name "${candidateName}" spelled`, true);
} else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {
// One point under the exact spelling, so the doc named `tokens` still
// outranks the Token component for `tokens`.
@@ -957,12 +1216,27 @@ export function scoreCandidate(
}
// ── Keyword signals ─────────────────────────────────────────────
+ const termJoined = joined(term);
for (const kw of keywords) {
const kwLower = String(kw).toLowerCase();
+ // A one-word keyword typed as separate words is the keyword: `number
+ // field` is `numberfield`. Only a
+ // lowercase keyword, one an author declares for a reader to type: a
+ // capitalized one names another entry (a block's `componentsUsed`). A
+ // doc's keywords include code terms, matched as written.
if (kwLower === term) {
consider(90, `keyword "${kw}"`);
continue;
}
+ if (
+ joins &&
+ domain !== 'doc' &&
+ /\s/.test(term) &&
+ String(kw) === termJoined
+ ) {
+ consider(90, `keyword "${kw}"`, true);
+ continue;
+ }
if (sameWord(term, kwLower)) {
consider(88, `keyword "${kw}"`);
continue;
@@ -994,9 +1268,12 @@ export function scoreCandidate(
// Match the term's stem as a whole word, tolerating plural/gerund suffixes
// so "chart" matches "charts" and "filter" matches "filtering".
if (term.length >= 3) {
- const root = stem(term);
- const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
- const re = new RegExp(`\\b${escaped}(s|es|ing|ed|ies)?\\b`);
+ // Any form of the term, with any common suffix: `spacing` finds
+ // "space" and "spaces", `sortable` finds "sorting".
+ const roots = [...new Set([stem(term), ...wordForms(term)])]
+ .filter(f => f.length >= 3)
+ .map(f => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+ const re = new RegExp(`\\b(?:${roots.join('|')})(s|es|ing|ed|ies)?\\b`);
if (description && re.test(description.toLowerCase())) {
consider(50, `description mentions "${term}"`);
} else {
@@ -1022,7 +1299,7 @@ export function scoreCandidate(
}
}
- return best > 0 ? {score: best, reason} : null;
+ return best > 0 ? {score: best, reason, ...(alias ? {alias} : {})} : null;
}
/**
@@ -1927,8 +2204,6 @@ async function searchOnce(query, options) {
}
const term = String(query).trim().toLowerCase();
- const tokens = tokenizeQuery(term);
-
// `astryx docs` reads docs without @astryxdesign/core, and `astryx theme
// list` reads themes without it (bundled themes need no project), so a
// search of either must too. Every other domain reads core: asked for by
@@ -1960,14 +2235,97 @@ async function searchOnce(query, options) {
const all = [...components, ...hooks, ...docTopics, ...templates, ...themes];
+ // A query that is one identifier counts as the words it spells
+ // (`SidebarToggle`), and still matches whole as typed. In a query of several
+ // words, each identifier stays one term (`ChatComposer ChatLayout` names two
+ // components), and its words still join into names (see compoundHit). Both
+ // only help a query that names no entry outright: when the query is an
+ // entry's name, typed whole or as its words, that entry answers it, and
+ // neither reading may add near siblings beside it.
+ const spelled = spellIdentifiers(String(query).trim());
+ const exact = all.some(candidate =>
+ [candidate.name, ...(candidate.aliases ?? [])].some(name => {
+ const lower = String(name).toLowerCase();
+ return (
+ lower === term ||
+ (candidate.domain !== 'doc' &&
+ !/[\s_-]/.test(lower) &&
+ lower === term.replace(/\s+/g, ''))
+ );
+ }),
+ );
+ // One identifier is read as its words only when, read whole, it matches
+ // nothing: a prop or hook name a doc already mentions keeps the
+ // entries that mention it.
+ const split =
+ !exact &&
+ !/\s/.test(term) &&
+ spelled !== term &&
+ !all.some(candidate => scoreCandidate(term, candidate));
+ const tokens = tokenizeQuery(split ? spelled : term);
+ /** @type {string[]} */
+ const words = exact
+ ? []
+ : phraseWords(split || /\s/.test(term) ? spelled : term);
+ // The entries the query names: a component, hook, or template whose whole
+ // name is adjacent query words joined (`icon button in a card header` names
+ // IconButton), or one identifier typed as such. A name inside a longer named
+ // run does not count (`icon` there is part of IconButton).
+ const queryWords = phraseWords(spelled);
+ const typedIdentifiers = new Set(
+ (String(query).match(/[A-Za-z0-9]+/g) ?? [])
+ .filter(w => /[A-Z]/.test(w))
+ .map(w => w.toLowerCase()),
+ );
+ /** @type {Map<string, [number, number]>} each run joined, longest first */
+ const spans = new Map();
+ for (let len = Math.min(queryWords.length, MAX_RUN_WORDS); len >= 1; len--) {
+ for (let a = 0; a + len <= queryWords.length; a++) {
+ // One plain word names too much (`list`, `field`); a named entry is a
+ // run of joined words, or an identifier typed as one.
+ if (len === 1 && !typedIdentifiers.has(queryWords[a])) continue;
+ const run = queryWords.slice(a, a + len).join('');
+ if (!spans.has(run)) spans.set(run, [a, a + len]);
+ }
+ }
+ const plainWords = new Set(queryWords);
+ /**
+ * Whether a query word is the candidate's whole name: such an entry keeps
+ * the rank its name earns, whatever else it matched.
+ * @param {Candidate} candidate
+ */
+ const wordNamed = candidate =>
+ candidate.domain !== 'doc' &&
+ [candidate.name, ...(candidate.aliases ?? [])].some(name => {
+ const n = joined(name);
+ return plainWords.has(n) || plainWords.has(`${n}s`);
+ });
+ /** @param {Candidate} candidate @returns {[number, number] | null} */
+ const namedSpan = candidate => {
+ if (candidate.domain === 'doc') return null;
+ /** @type {[number, number] | null} */
+ let best = null;
+ for (const name of [candidate.name, ...(candidate.aliases ?? [])]) {
+ const n = joined(name);
+ const span =
+ spans.get(n) ??
+ spans.get(`${n}s`) ??
+ (/(?:s|x|z|ch|sh)$/.test(n) ? spans.get(`${n}es`) : undefined);
+ if (span && (!best || span[1] - span[0] > best[1] - best[0])) {
+ best = span;
+ }
+ }
+ return best;
+ };
+
// Score every candidate on its own merits. The consumer groups results by
// role (page / block / component) and takes the top of each, so there's no
// cross-role competition to engineer — a target page only needs to be the
// strongest PAGE, not outrank every component.
- /** @type {{result: any, priority: 0 | 1 | 2}[]} */
+ /** @type {{result: any, priority: 0 | 1 | 2, key: number, alias: boolean, candidate: Candidate, span: [number, number] | null, word: boolean}[]} */
const ranked = [];
for (const candidate of all) {
- const hit = scoreQuery(term, tokens, candidate);
+ const hit = scoreQuery(term, tokens, candidate, words);
if (hit)
ranked.push({
result: toResult(
@@ -1977,9 +2335,43 @@ async function searchOnce(query, options) {
hit.matched,
hit.total,
),
- priority: domainPriority(term, tokens, candidate, hit),
+ priority: domainPriority(term, tokens, candidate, hit, words),
+ key: hit.score,
+ alias: hit.alias === true,
+ candidate,
+ span: namedSpan(candidate),
+ word: wordNamed(candidate),
});
}
+ // A match through part of a name or a keyword read joined never outranks
+ // an entry the query names: `table header with sticky columns` keeps
+ // TableHeader above useTableStickyColumns, which only holds the words
+ // `sticky columns`. Only the order changes; each result keeps the score its
+ // text earned.
+ /** @param {[number, number]} inner @param {[number, number]} outer */
+ const inside = (inner, outer) =>
+ outer[0] <= inner[0] &&
+ outer[1] >= inner[1] &&
+ outer[1] - outer[0] > inner[1] - inner[0];
+ const named = ranked.filter(r => {
+ const span = r.span;
+ return (
+ span != null &&
+ !ranked.some(o => o !== r && o.span != null && inside(span, o.span))
+ );
+ });
+ if (named.length > 0) {
+ const floor = Math.min(...named.map(r => r.key));
+ for (const r of ranked) {
+ if (r.alias && !named.includes(r) && !r.word) {
+ // It keeps what it earns without those matches.
+ const own =
+ scoreQuery(term, tokens, r.candidate, words, {plain: true})?.score ??
+ 0;
+ r.key = Math.max(own, Math.min(r.key, floor - 0.5));
+ }
+ }
+ }
// Docs and everything else are each sorted by score desc, then domain
// (stable order), then name. The two are merged: at each step the stronger
@@ -1988,11 +2380,11 @@ async function searchOnce(query, options) {
/** @type {Record<string, number>} */
const domainOrder = {component: 0, hook: 1, doc: 2, template: 3, theme: 4};
/**
- * @param {{result: any}} x
- * @param {{result: any}} y
+ * @param {{result: any, key: number}} x
+ * @param {{result: any, key: number}} y
*/
- const byScore = ({result: a}, {result: b}) =>
- b.score - a.score ||
+ const byScore = ({result: a, key: ka}, {result: b, key: kb}) =>
+ kb - ka ||
(domainOrder[a.domain] ?? 9) - (domainOrder[b.domain] ?? 9) ||
a.name.localeCompare(b.name);
const others = ranked.filter(r => r.result.domain !== 'doc').sort(byScore);
diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjs
index de763fb22c..640907ed29 100644
--- a/packages/cli/api/search/search.test.mjs
+++ b/packages/cli/api/search/search.test.mjs
@@ -863,3 +863,131 @@ describe('search — usage guidance is indexed, a tier below description', () =>
expect(hit?.score).toBe(45);
});
});
+
+describe('search leaf — compound names, other names, and word forms', () => {
+ it('finds a compound name typed as separate words inside a longer query', async () => {
+ const {data} = await search('table header cell with sort arrow', {cwd});
+ expect(
+ data.results.slice(0, 3).map(r => r.name),
+ ).toContain('TableHeaderCell');
+ }, SLOW);
+
+ it('finds a one-word keyword typed as separate words', async () => {
+ // MetadataList declares `keyvalue`.
+ const {data} = await search('key value pairs', {cwd});
+ expect(data.results[0]).toMatchObject({
+ domain: 'component',
+ name: 'MetadataList',
+ });
+ }, SLOW);
+
+ it('finds a hook named by its words without the `use` prefix', async () => {
+ const {data} = await search('persisted table column settings', {cwd});
+ expect(data.results[0]).toMatchObject({
+ domain: 'hook',
+ name: 'useTableColumnSettings',
+ });
+ }, SLOW);
+
+ it('reads a camelCase identifier as the words it spells', async () => {
+ const {data} = await search('useTablePaginationState', {cwd});
+ expect(data.results[0]).toMatchObject({
+ domain: 'hook',
+ name: 'useTablePagination',
+ });
+ }, SLOW);
+
+ it('keeps each identifier of a multi-word query whole', async () => {
+ const {data} = await search('ChatMessageList ChatComposer', {cwd});
+ expect(data.results.slice(0, 2).map(r => r.name).sort()).toEqual([
+ 'ChatComposer',
+ 'ChatMessageList',
+ ]);
+ }, SLOW);
+
+ it("finds a component by another library's name for it", async () => {
+ for (const [q, name] of [
+ ['ScrollArea viewport', 'ScrollableArea'],
+ ['toggle group of buttons', 'ToggleButtonGroup'],
+ ['circular progress for uploads', 'Spinner'],
+ ]) {
+ const {data} = await search(q, {cwd});
+ expect(data.results[0], q).toMatchObject({domain: 'component', name});
+ }
+ }, SLOW);
+
+ it('reads a one-identifier other name as typed', async () => {
+ const {data} = await search('AppHeader', {cwd});
+ expect(data.results[0]).toMatchObject({
+ domain: 'component',
+ name: 'LayoutHeader',
+ });
+ }, SLOW);
+
+ it('adds no near siblings beside an entry the query names outright', async () => {
+ const {data} = await search('top nav mega menu', {cwd});
+ expect(data.results[0]).toMatchObject({name: 'TopNavMegaMenu'});
+ // Its sub-parts start with its name; read joined they would score in the
+ // whole-name tier right under it.
+ const siblings = data.results.filter(
+ r => r.name !== 'TopNavMegaMenu' && r.name.startsWith('TopNavMegaMenu'),
+ );
+ for (const sibling of siblings) expect(sibling.score).toBeLessThan(190);
+ }, SLOW);
+
+ it('ranks an entry the query names above a match on part of another name', async () => {
+ // `table header` names TableHeader; useTableStickyColumns only holds the
+ // words `sticky columns`.
+ const {data} = await search('table header with sticky columns', {cwd});
+ const names = data.results.map(r => r.name);
+ expect(names.indexOf('TableHeader')).toBeLessThan(
+ names.indexOf('useTableStickyColumns') === -1
+ ? Infinity
+ : names.indexOf('useTableStickyColumns'),
+ );
+ }, SLOW);
+
+ it('keeps an entry a query word names by its whole name at its own rank', async () => {
+ // Two words join into TextInput, and TextArea also matches two words
+ // through its joined keyword; one word is still TextArea's whole name.
+ const {data} = await search('text input and textarea with multi line', {
+ cwd,
+ });
+ expect(data.results[0]).toMatchObject({name: 'TextArea'});
+ }, SLOW);
+
+ it('finds Icon by a glyph name', async () => {
+ for (const q of ['cog', 'lightning bolt']) {
+ const {data} = await search(q, {cwd});
+ expect(data.results[0], q).toMatchObject({
+ domain: 'component',
+ name: 'Icon',
+ });
+ }
+ }, SLOW);
+
+ it('matches a verb form against its verb', () => {
+ // "spacing" lost the final e of "space".
+ expect(
+ scoreCandidate('spacing', {domain: 'component', name: 'Gap', keywords: ['space']}),
+ ).toMatchObject({score: 88});
+ expect(
+ scoreCandidate('dragging', {domain: 'component', name: 'Gap', keywords: ['drag']}),
+ ).toMatchObject({score: 88});
+ });
+
+ it('lets a plural start a longer word through its singular', () => {
+ expect(
+ scoreCandidate('chips', {domain: 'component', name: 'Chipset'}),
+ ).toMatchObject({score: 60});
+ // A four-letter singular is too short: "stats" does not start "statusbar".
+ expect(
+ scoreCandidate('stats', {domain: 'component', name: 'Statusbar'}),
+ ).toBeNull();
+ });
+
+ it('leaves an identifier joined with _ unmatched when nothing has it', async () => {
+ const {data} = await search('qqzz_no_match_here', {cwd});
+ expect(data.results).toEqual([]);
+ }, SLOW);
+});
diff --git a/packages/core/src/Code/Code.doc.mjs b/packages/core/src/Code/Code.doc.mjs
index 1a4c17d934..e08560fc8a 100644
--- a/packages/core/src/Code/Code.doc.mjs
+++ b/packages/core/src/Code/Code.doc.mjs
@@ -4,6 +4,7 @@
export const docs = {
name: 'Code',
displayName: 'Code',
+ keywords: ['inlinecode', 'monospace'],
group: 'Code',
category: 'Content',
description:
diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
index 65eabe8e63..c15ef44d1e 100644
--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
@@ -87,6 +87,8 @@ export const docs = {
'modal',
'dialog',
'navigation',
+ 'commandmenu',
+ 'cmdk',
],
description:
'Root component. Manages open state, search, keyboard navigation, and composition slots.',
diff --git a/packages/core/src/Drawer/Drawer.doc.mjs b/packages/core/src/Drawer/Drawer.doc.mjs
index 757079e805..7b33dd420f 100644
--- a/packages/core/src/Drawer/Drawer.doc.mjs
+++ b/packages/core/src/Drawer/Drawer.doc.mjs
@@ -55,6 +55,7 @@ export const docs = {
'sidebar',
'dialog',
'side drawer',
+ 'sidesheet',
],
// No isInline docs-preview prop (the drawer has no inline containment), so
// this is the overlay preview: closed on load with an open trigger, knobs
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index eb6637fc8a..fc5c703c0f 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -23,6 +23,42 @@ export const docs = {
'pictogram',
'graphic',
'vector',
+ 'arrow',
+ 'chevron',
+ 'caret',
+ 'checkmark',
+ 'cross',
+ 'gear',
+ 'cog',
+ 'broom',
+ 'sparkle',
+ 'sparkles',
+ 'star',
+ 'heart',
+ 'bell',
+ 'trash',
+ 'pencil',
+ 'magnifyingglass',
+ 'paperclip',
+ 'house',
+ 'flame',
+ 'rocket',
+ 'lightning',
+ 'bolt',
+ 'globe',
+ 'sun',
+ 'moon',
+ 'bookmark',
+ 'thumbsup',
+ 'smiley',
+ 'emoji',
+ 'lock',
+ 'eye',
+ 'cloud',
+ 'hourglass',
+ 'trophy',
+ 'gift',
+ 'camera',
],
playground: {
// `icon` is required and its type can't be auto-generated, so the
diff --git a/packages/core/src/Layout/LayoutHeader.doc.mjs b/packages/core/src/Layout/LayoutHeader.doc.mjs
index b2cea18b03..2aa8e1a9af 100644
--- a/packages/core/src/Layout/LayoutHeader.doc.mjs
+++ b/packages/core/src/Layout/LayoutHeader.doc.mjs
@@ -6,6 +6,11 @@ export const docs = {
name: 'LayoutHeader',
subComponentOf: 'Layout',
displayName: 'Layout Header',
+ keywords: [
+ 'pageheader',
+ 'appheader',
+ 'header',
+ ],
isHiddenFromOverview: true,
description: 'Top bar for page titles, app bars, and toolbars.',
playground: {
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index d5185aab2d..0d59a98596 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
displayName: 'Metadata List',
group: 'MetadataList',
category: 'Table & List',
- keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],
+ keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary","descriptionlist","descriptions"],
theming: {
targets: [
{
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index 3e3de808d7..d4105cd756 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -53,6 +53,7 @@ export const docs = {
'determinate',
'indeterminate',
'meter',
+ 'linearprogress',
],
props: [
{
diff --git a/packages/core/src/Resizable/useResizable.doc.mjs b/packages/core/src/Resizable/useResizable.doc.mjs
index b644a2c734..863b6afb76 100644
--- a/packages/core/src/Resizable/useResizable.doc.mjs
+++ b/packages/core/src/Resizable/useResizable.doc.mjs
@@ -14,6 +14,9 @@ export const docs = {
'sidebar',
'divider',
'splitter',
+ 'splitpane',
+ 'splitview',
+ 'resizablepanels',
],
params: [
{
diff --git a/packages/core/src/ScrollableArea/ScrollableArea.doc.mjs b/packages/core/src/ScrollableArea/ScrollableArea.doc.mjs
index 8c639db474..65b366f519 100644
--- a/packages/core/src/ScrollableArea/ScrollableArea.doc.mjs
+++ b/packages/core/src/ScrollableArea/ScrollableArea.doc.mjs
@@ -5,7 +5,7 @@ export const docs = {
name: 'ScrollableArea',
displayName: 'Scrollable Area',
category: 'Layout',
- keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed'],
+ keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed', 'scrollarea', 'scrollview'],
usage: {
description: 'Provides a native scroll viewport and a real observed content box. The viewport enters the tab order only while a requested logical axis is effectively scrollable, and containment applies only to effective axes.',
bestPractices: [
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index 788054af05..4b7d031a93 100644
--- a/packages/core/src/Spinner/Spinner.doc.mjs
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
name: 'Spinner',
displayName: 'Spinner',
category: 'Feedback & Status',
- keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate"],
+ keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate","circularprogress"],
props: [
{
name: 'size',
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index 9a17832c0e..00b29f5e15 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
name: 'Timestamp',
displayName: 'Timestamp',
category: 'Content',
- keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration'],
+ keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration', 'relativetime'],
playground: {
// `value` is required but has no semantic default, so the properties-tab
// preview fell back to the literal string "value" — which
diff --git a/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs b/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs
index 9819c88a41..d2c754d0d7 100644
--- a/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs
@@ -6,6 +6,10 @@ export const docs = {
name: 'ToggleButtonGroup',
subComponentOf: 'ToggleButton',
displayName: 'Toggle Button Group',
+ keywords: [
+ 'togglegroup',
+ 'buttontogglegroup',
+ ],
description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
props: [
{