An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file One search term's score against one candidate: name, keyword, prose,
* and typo signals.
*
* Scoring is keyword + fuzzy ranking (NOT semantic / embeddings — that is a
* deliberate future follow-up). It reuses the same signal weighting as the
* component fuzzy resolver in lib/string-utils.mjs:
*
* 100 exact name match
* 95 name is the term's plural or stem form ("buttons" -> Button)
* 90 exact keyword match
* 88 keyword is the term's plural or stem form
* 80 name Levenshtein distance 1 (one-word lookups, words of 5+ letters)
* 70 keyword word prefix / distance 1 (distance: one-word lookups, 5+ letters)
* 60 name word prefix (>=4 chars, >=50% coverage)
* 60 exact weak-keyword match
* 50 description / prose mentions the term
* 45 usage guidance mentions the term
* 40 name Levenshtein distance 2 (one-word lookups, 8+ letters)
* 40 weak-keyword word prefix
* 30 keyword Levenshtein distance 2 (one-word lookups, 8+ letters)
* 20 name Levenshtein distance 3 (one-word lookups, 11+ letters)
*
* Name + keyword signals always outweigh description/prose, so an exact match
* sorts above an incidental mention.
*
* A term matches inside a name or keyword only at the start of one of its
* words: "dash" finds "dashboard" and "input" finds "TextInput", but "file"
* does not find "profile". Edit distance is typo tolerance, so it applies only
* to a one-word lookup, where a typo is the likely explanation, and only to
* words long enough that one edit rarely makes another real word. In a
* sentence, a near miss is usually a different word: "site" is not "side",
* "cable" is not "table".
*/
import {
stem,
sameWord,
sameTermWord,
startsATermWordOf,
termWords,
wordsOf,
joined,
typoDistance,
} from './_words.mjs';
import {pluralOf} from './_query.mjs';
/**
* Whether a multi-word term spells out a name word by word: as many words as
* the name, each the name's word in order or, for a single-letter word, a word
* starting with that letter ("vertical" for V) that the entry's own
* description names. `vertical stack` spells out VStack when its description says
* "vertical"; `visual stack` does not.
* @param {string} term
* @param {string} name
* @param {string} description
*/
function spellsOut(term, name, description) {
const words = term.split(/\s+/).filter(Boolean);
const parts = wordsOf(name);
if (words.length < 2 || words.length !== parts.length) return false;
const described = wordsOf(description);
let expanded = false;
for (let i = 0; i < words.length; i++) {
const w = words[i];
const p = parts[i];
if (sameWord(w, p)) continue;
// Only a single-letter word is an abbreviation to spell out: "With" in a
// name is not spelled out by "without".
if (p.length !== 1 || !w.startsWith(p)) return false;
if (!described.some(d => sameWord(d, w))) return false;
expanded = true;
}
return expanded;
}
/**
* Whether a one-word term is a name's last word and every word before it is a
* single letter: Stack in VStack and HStack.
* @param {import('./_words.mjs').TermWords} t
* @param {string} name
*/
function headOfLetters(t, name) {
const parts = wordsOf(name);
return (
parts.length >= 2 &&
sameTermWord(t, parts[parts.length - 1]) &&
parts.slice(0, -1).every(p => p.length === 1)
);
}
/** How many of a family's members a query naming the family lists. */
const FAMILY_MEMBERS = 3;
/**
* A derived name's score for a term: 60 for the same word, 40 for a word the
* term starts, else 0.
* @param {import('./_words.mjs').TermWords} t - The lowercased search term.
* @param {string} kw - The derived name as authored.
* @returns {number}
*/
function weakKeywordScore(t, kw) {
const kwLower = String(kw).toLowerCase();
if (kwLower === t.term || sameTermWord(t, kwLower)) return 60;
return startsATermWordOf(t, kw) ? 40 : 0;
}
/**
* Score a single candidate against the search term across name, keywords,
* and prose signals. Returns the best (highest) score plus a human reason,
* or null if nothing matched above the floor.
*
* @param {string} term - Lowercased search term.
* @param {object} candidate
* @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
* @param {string[]} [candidate.aliases] - Other names, scored like the name (a theme's display name).
* @param {string} [candidate.domain] - A component, hook, or template name
* also matches typed as words: `command palette` is CommandPalette.
* @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
* @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
* @param {string[]} [candidate.weakKeywordBound] - Every name `weakKeywords`
* can hold, when reading them is costly: they are read only if one matches.
* @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 {string} [candidate._family] - The family whose doc lists the entry as a member.
* @param {number} [candidate._familyIndex] - The entry's place among that family's members.
* @param {{fuzzy?: boolean, joins?: boolean, part?: boolean, synonym?: 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. `part`: the term is one word of a longer query, so a name's head word after single letters (Stack in VStack) does not count as a keyword hit for it. `synonym`: the term stands in for a word of the query, so it names no family.
* @returns {{score: number, reason: string, alias?: 'partial' | 'keyword'} | null}
* `alias` marks a hit that read the query's words joined.
*/
export function scoreCandidate(
term,
candidate,
{fuzzy = true, joins = true, part = false, synonym = false} = {},
) {
const {
name,
aliases = [],
domain,
keywords = [],
description = '',
prose = [],
guidance = [],
_family,
_familyIndex,
} = candidate;
// The term's forms, worked out once for every word below.
const t = termWords(term);
let best = 0;
let reason = '';
/** @type {'partial' | 'keyword' | false} */
let alias = false;
/**
* @param {number} score
* @param {string} why
* @param {'partial' | 'keyword' | false} [byAlias] - the hit reads the
* query's words joined, into part of a name or into a keyword
*/
const consider = (score, why, byAlias = false) => {
if (score > best) {
best = score;
reason = why;
alias = byAlias;
}
};
// ── Name signals ────────────────────────────────────────────────
// An alias is a name too: a theme answers to its display name as well as
// its slug.
for (const candidateName of [name, ...aliases.filter(Boolean)]) {
const nameLower = candidateName.toLowerCase();
// A placed guide's name is its route, and the route's last segment is its
// name too, as a flat topic's is: `codemods` is authoring/building-blocks/codemods.
const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);
// A plural of the name is the name: `integration` is the `integrations`
// guides, `tab` the `tabs` doc.
// A component, hook, or template name typed as words is its name:
// `command palette` is CommandPalette. A doc's name is a route or key,
// matched as written.
const spelled =
domain !== 'doc' &&
!/[\s_-]/.test(nameLower) &&
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`, 'partial');
} else if (
domain !== 'doc' &&
domain !== 'theme' &&
spellsOut(term, candidateName, description)
) {
// The name's short words spelled out, in order, as the entry's own
// description spells them: `vertical stack` is VStack ("Vertical stack
// for arranging items top-to-bottom").
consider(95, `name "${candidateName}" spelled out`);
} 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`.
consider(99, 'plural of the name');
} else {
if (sameTermWord(t, nameLower)) consider(95, `name "${candidateName}"`);
// The term is a word of the name, or starts one: "input" in TextInput.
else if (
!part &&
domain !== 'doc' &&
domain !== 'theme' &&
headOfLetters(t, candidateName)
) {
// The whole query is the name's head word after single letters (Stack
// in VStack, HStack): a variant named by its head, as a keyword is.
consider(90, `name "${candidateName}" ends in "${term}"`);
} else if (startsATermWordOf(t, candidateName)) {
consider(60, `name contains "${term}"`);
}
if (fuzzy) {
const dist = typoDistance(term, nameLower);
if (dist != null) {
consider(
dist === 1 ? 80 : dist === 2 ? 40 : 20,
`similar name (distance ${dist})`,
);
}
}
}
}
// ── Family signal ───────────────────────────────────────────────
// A query naming a family lists its first members as a keyword would: the
// family doc names them, whether or not a component of the family's name
// exists ("chat" lists ChatMessage and its siblings). Only the whole query
// names the family: a word of a longer query lifts no member.
if (
!part &&
!synonym &&
_family &&
(_familyIndex ?? Infinity) < FAMILY_MEMBERS &&
(term === _family.toLowerCase() ||
term === wordsOf(_family).join(' ') ||
term.replace(/\s+/g, '') === _family.toLowerCase())
) {
consider(90, `member of ${_family}`);
}
// ── 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}"`, 'keyword');
continue;
}
if (sameTermWord(t, kwLower)) {
consider(88, `keyword "${kw}"`);
continue;
}
if (startsATermWordOf(t, kw)) consider(70, `keyword "${kw}"`);
if (fuzzy) {
const dist = typoDistance(term, kwLower);
if (dist != null && dist <= 2) {
consider(dist === 1 ? 70 : 30, `keyword "${kw}" (distance ${dist})`);
}
}
}
// ── Weak keyword signals (derived, not authored) ─────────────────
// Capped at 60 so one incidental component match cannot clear the
// confident-match gate on its own; it still counts toward multi-term
// coverage, which is where "this page renders that" is real evidence.
// No Levenshtein tier — fuzzy matching a derived signal is pure noise.
// A bound skips the read when no name the page can yield matches the term,
// and then no weak keyword can match it either.
const bound = candidate.weakKeywordBound;
if (!bound || bound.some(kw => weakKeywordScore(t, kw) > 0)) {
for (const kw of candidate.weakKeywords ?? []) {
const score = weakKeywordScore(t, kw);
if (score > 0) consider(score, `renders ${kw}`);
}
}
// ── Prose / description / guidance signals (stem-tolerant whole word) ──
// 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) {
// Any form of the term, with any common suffix: `spacing` finds
// "space" and "spaces", `tables` finds "table".
const roots = [...new Set([stem(term), ...t.forms])]
.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 {
let matchedProse = false;
for (const blob of prose) {
if (blob && re.test(String(blob).toLowerCase())) {
consider(50, `docs mention "${term}"`);
matchedProse = true;
break;
}
}
// A tier below prose: guidance is what a component says about USING it,
// so the term appearing there is weaker evidence than the component's own
// summary. Only consulted when nothing stronger matched.
if (!matchedProse) {
for (const blob of guidance) {
if (blob && re.test(String(blob).toLowerCase())) {
consider(45, `guidance mentions "${term}"`);
break;
}
}
}
}
}
return best > 0 ? {score: best, reason, ...(alias ? {alias} : {})} : null;
}