Skip to content

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

TypeScript

fix(search): name a guide by its route or title whatever the plural (#7229)

Joeyf8cd9490016e
diff --git a/.changeset/search-plural-doc-names.md b/.changeset/search-plural-doc-names.md
new file mode 100644
index 0000000000..6982c7d847
--- /dev/null
+++ b/.changeset/search-plural-doc-names.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx search` finds a guide when the query is its route or title in the other number: `side panel` finds the side panels guide first again, and `header and footer` finds headers and footers. A section's heading still doesn't count as its topic's name, so `font size` keeps finding Text first.
+
+@josephfarina
diff --git a/packages/cli/api/search/search.domain-priority.test.mjs b/packages/cli/api/search/search.domain-priority.test.mjs
index fb7599b48a..f0df3d168e 100644
--- a/packages/cli/api/search/search.domain-priority.test.mjs
+++ b/packages/cli/api/search/search.domain-priority.test.mjs
@@ -96,6 +96,35 @@ describe('search domain priority — the rule', () => {
).toBe(1);
});
+ it('names a doc by its route or title whatever the plural', () => {
+ const guide = {
+ domain: 'doc',
+ name: 'layout/side-panels',
+ titles: ['Side panels'],
+ };
+ expect(priority('side panel', guide)).toBe(2);
+ expect(priority('side panels', guide)).toBe(2);
+ expect(priority('side panels', {...guide, name: 'layout/side-panel'})).toBe(
+ 2,
+ );
+ // The topic's own title names it even where the route words differ.
+ const titled = {
+ domain: 'doc',
+ name: 'guides/lookups',
+ titles: ['Looking up components'],
+ };
+ expect(priority('looking up component', titled)).toBe(2);
+ // A section's title is a heading inside its topic, not the topic's name.
+ const section = {
+ domain: 'doc',
+ name: 'font-sizes',
+ _topic: 'typography',
+ _section: 'font-sizes',
+ titles: ['Font Sizes'],
+ };
+ expect(priority('font size', section)).toBe(0);
+ });
+
it('names a section by its topic', () => {
// A section candidate's own name is its section key; the reader names the
// topic it belongs to.
@@ -210,30 +239,15 @@ describe('search domain priority — real docs and components', () => {
);
it(
- 'still finds a split topic first by its own name, in every namespace',
+ 'still finds each layout guide first by its own name',
async () => {
- const guides = [];
- for (const ns of ['layout', 'typography', 'tokens', 'styling', 'cli']) {
- guides.push(...(await placedGuides(ns)));
- }
- // The layout split is in the tree; the walk covers whatever else is.
+ // Each search reads the whole index, so this checks one split namespace
+ // (layout, six guides) rather than every guide in the tree.
+ const guides = await placedGuides('layout');
expect(guides).toContain('layout/layout-spacing');
- // Each search reads the whole index, so check one guide per namespace
- // (its first, in route order): every split is covered without a search
- // per guide.
- /** @type {Map<string, string>} */
- const firstPerNamespace = new Map();
- for (const route of [...new Set(guides)].sort()) {
- const ns = route.slice(0, route.lastIndexOf('/'));
- if (!firstPerNamespace.has(ns)) firstPerNamespace.set(ns, route);
- }
- const sample = new Set([
- 'layout/layout-spacing',
- ...firstPerNamespace.values(),
- ]);
/** @type {string[]} */
const misses = [];
- for (const route of sample) {
+ for (const route of guides) {
const q = route.slice(route.lastIndexOf('/') + 1).replace(/-/g, ' ');
const top = (await search(q, {cwd})).data.results[0];
if (top?.domain !== 'doc' || top.name !== route) {
@@ -242,6 +256,6 @@ describe('search domain priority — real docs and components', () => {
}
expect(misses).toEqual([]);
},
- SLOW * 2,
+ SLOW,
);
});
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 5066a2646f..d764eb51c0 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -494,8 +494,9 @@ const STRONG_TOKEN_SCORE = 70;
* {@link STRONG_TOKEN_SCORE} or above, or when it matches every word.
*
* A doc has priority when the reader asked for that doc:
- * - 2: the whole query spells the topic's name or its last route segment
- * (`font setup` is typography/font-setup, `motion` is the motion guide);
+ * - 2: the whole query is the topic's name, its last route segment, or its
+ * own title, as words and whatever the plural (`font setup` is
+ * typography/font-setup, `side panel` is "Side panels");
* - 1: a word of the query is the topic's name (`illustration` in a longer
* question is the illustrations guide);
* - 1: the query holds one of the doc's titles whole (`resizable side panels`
@@ -525,13 +526,15 @@ export function domainPriority(term, tokens, candidate, hit) {
const words = [term, ...tokens];
if (candidate.domain === 'doc') {
const topic = String(candidate._topic ?? candidate.name).toLowerCase();
- const asWords = (/** @type {string} */ n) =>
- n.replace(/[-_\s]+/g, ' ').trim();
- const spelled = asWords(term);
- if (
- asWords(topic) === spelled ||
- asWords(topic.slice(topic.lastIndexOf('/') + 1)) === spelled
- ) {
+ // The whole query, read as words, is the topic's route, its last
+ // segment, or its own title, whatever the plural: `side panel` is
+ // layout/side-panels, and `header and footer` is "Headers and footers".
+ // A section's title is a heading inside a topic, not the topic's name.
+ const named = [topic, topic.slice(topic.lastIndexOf('/') + 1)];
+ if (candidate._section == null && candidate.titles?.[0]) {
+ named.push(candidate.titles[0]);
+ }
+ if (named.some(n => samePhrase(term, n))) {
return 2;
}
if (
@@ -602,6 +605,24 @@ function samePhraseWord(a, b) {
);
}
+/**
+ * Whether two phrases are the same words, in order, ignoring case,
+ * punctuation, and a plural on any word: `side panel` is "Side panels", and
+ * `headers and footers` is `header-and-footer`.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function samePhrase(a, b) {
+ const x = phraseWords(a);
+ const y = phraseWords(b);
+ return (
+ x.length > 0 &&
+ x.length === y.length &&
+ x.every((w, k) => samePhraseWord(w, y[k]) || sameWord(w, y[k]))
+ );
+}
+
/**
* Whether `plural` is the plural of `word`: `integrations` of `integration`,
* `boxes` of `box`. `es` only follows s, x, z, ch, or sh, so `notes` is not a