Skip to content

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

TypeScript
20.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file `icon()` (AST-084 FR6, FR7): ranking, set and limit options, one
 * icon, the set list, and errors, over the synthetic fixture.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {icon} from './icon.mjs';
import {iconUse} from './use/use.mjs';
import {iconMap} from './map/map.mjs';
import {iconAdd} from './add/add.mjs';
import {iconNewDefinition} from './new-definition/new-definition.mjs';
import {ICON_NAMES} from '../../authoring/doctypes/icon-set/icon-names.mjs';
import {answeringMatches, rankIcons, scoreIcon} from './_records.mjs';
import {
  glyphsData,
  writeIconPackage,
  writeIconSetProject,
} from '../../test-utils/icon-set-fixture.mjs';

/** @type {string} */
let tmp;
/** @type {string} */
let cwd;
beforeEach(() => {
  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-icon-api-'));
  cwd = writeIconSetProject(tmp);
});
afterEach(() => {
  fs.rmSync(tmp, {recursive: true, force: true});
});

/** @param {string} query @param {object} [options] */
async function search(query, options = {}) {
  const result = await icon(query, {cwd, ...options});
  if (result.type !== 'icon.search') throw new Error(result.type);
  return result.data;
}

describe('icon.search ranking', () => {
  const icons = glyphsData().icons;
  const byId = (/** @type {string} */ id) =>
    /** @type {any} */ (icons.find(each => each.id === id));

  it('scores each tier: definition, exact in the leading reading, exact in the other, prefix, partial', () => {
    expect(scoreIcon('close', byId('x'), 'meaning', ['close'])).toEqual({
      score: 100,
      reason: 'definition "close"',
    });
    expect(scoreIcon('trash', byId('trash'), 'name')).toEqual({
      score: 90,
      reason: 'id "trash"',
    });
    expect(scoreIcon('trash', byId('trash'), 'meaning')).toEqual({
      score: 80,
      reason: 'id "trash"',
    });
    expect(scoreIcon('delete', byId('trash'))).toEqual({
      score: 90,
      reason: 'word "delete"',
    });
    expect(scoreIcon('delete', byId('trash'), 'name')?.score).toBe(80);
    expect(scoreIcon('garb', byId('trash'))?.score).toBe(60);
    expect(scoreIcon('arbag', byId('trash'))?.score).toBe(40);
    expect(scoreIcon('ma', byId('search'))?.score).toBe(60);
    expect(scoreIcon('zebra', byId('trash'))).toBeNull();
  });

  it('a fill outranks a word match of the same text', async () => {
    const data = await search('search');
    expect(data.matches[0]).toMatchObject({id: 'search', score: 100});
  });

  it('ties keep id order, so the answer is stable', async () => {
    const data = await search('remove');
    expect(data.matches.map(match => match.id)).toEqual(['trash', 'x']);
  });

  it('ties keep set order: the project set first', () => {
    const set = (/** @type {string} */ name) =>
      /** @type {any} */ ({
        name,
        package: `@acme/${name}`,
        data: {module: `@acme/${name}`, icons: [byId('x')]},
      });
    expect(rankIcons([set('b'), set('a')], 'close').map(m => m.set)).toEqual([
      'b',
      'a',
    ]);
  });

  it("equal scores keep set order before tag position: the project's set leads", () => {
    const glyphs = /** @type {any} */ ({
      name: 'glyphs',
      package: '@acme/glyphs',
      data: {
        module: '@acme/glyphs',
        icons: [{id: 'bin', export: 'BinIcon', words: ['garbage', 'delete']}],
      },
    });
    const other = /** @type {any} */ ({
      name: 'other',
      package: '@acme/other',
      data: {
        module: '@acme/other',
        icons: [{id: 'trash', export: 'TrashIcon', words: ['delete']}],
      },
    });
    const ranked = rankIcons([glyphs, other], 'delete');
    expect(ranked.map(m => [m.set, m.id])).toEqual([
      ['glyphs', 'bin'],
      ['other', 'trash'],
    ]);
    expect(ranked[0].score).toBe(ranked[1].score);
  });

  it('returns every field, with the import line', async () => {
    const data = await search('delete');
    expect(data).toMatchObject({query: 'delete', matchCount: 1});
    expect(data.matches[0]).toEqual({
      set: 'glyphs',
      id: 'trash',
      package: '@acme/glyphs',
      module: '@acme/glyphs',
      export: 'TrashIcon',
      import: "import {TrashIcon} from '@acme/glyphs';",
      words: ['delete', 'remove', 'bin', 'garbage'],
      definitions: [],
      variants: [
        {variant: 'solid', module: '@acme/glyphs', export: 'TrashSolidIcon'},
      ],
      reason: 'word "delete"',
      score: 90,
    });
  });

  it('no match is an empty list, not an error', async () => {
    expect(await search('zebra')).toEqual({
      query: 'zebra',
      matchCount: 0,
      matches: [],
    });
  });

  it('--limit caps the list; matchCount counts every match', async () => {
    const data = await search('remove', {limit: 1});
    expect(data.matches).toHaveLength(1);
    expect(data.matchCount).toBe(2);
    await expect(icon('remove', {cwd, limit: 0})).rejects.toMatchObject({
      code: 'ERR_INVALID_ARGUMENT',
    });
  });

  it('--set keeps one set, and an unknown set is ERR_NOT_FOUND', async () => {
    expect(
      (await search('close', {set: '@acme/glyphs/glyphs'})).matchCount,
    ).toBe(1);
    await expect(icon('close', {cwd, set: 'glyps'})).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      suggestions: expect.arrayContaining([
        expect.objectContaining({name: 'glyphs'}),
      ]),
    });
  });

  it('a project with no icon set answers an empty list', async () => {
    fs.rmSync(path.join(cwd, 'node_modules'), {recursive: true});
    expect((await search('close')).matches).toEqual([]);
  });
});

describe('icon.search: an exact query reads as a name or a meaning', () => {
  /**
   * @param {Array<[string, string[]]>} icons id and words
   * @returns {any}
   */
  const set = icons => ({
    name: 'lines',
    package: '@acme/lines',
    data: {
      module: '@acme/lines',
      icons: icons.map(([id, words]) => ({
        id,
        export: `${id.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase())}Icon`,
        words,
      })),
    },
  });
  /** @param {any} s @param {string} q */
  const ranked = (s, q) =>
    rankIcons([s], q).map(m => [m.id, m.score, m.reason]);

  it('meaning wins: `delete` finds trash before the icon that draws the Delete key', () => {
    // The shape of a large outline library's data: an icon's own id words
    // come first, then its tags.
    const lines = set([
      ['delete', ['delete', 'backspace', 'key']],
      ['trash', ['trash', 'delete', 'remove', 'bin']],
    ]);
    expect(ranked(lines, 'delete')).toEqual([
      ['trash', 90, 'word "delete"'],
      ['delete', 80, 'id "delete"'],
    ]);
  });

  it('a word many icons are named for stays a name: `user` keeps the user icon ahead of one only tagged user', () => {
    const lines = set([
      ['contact', ['contact', 'user', 'person']],
      ['user', ['user', 'person', 'account']],
      ['user-plus', ['user', 'plus', 'add']],
    ]);
    expect(ranked(lines, 'user')).toEqual([
      ['user', 90, 'id "user"'],
      ['user-plus', 90, 'word "user"'],
      ['contact', 80, 'word "user"'],
    ]);
  });

  it('within the leading reading the tag listed earlier wins, and a tie in counts lets meaning lead', () => {
    const lines = set([
      ['eraser', ['eraser', 'rubber', 'clear', 'delete']],
      ['trash', ['trash', 'delete', 'remove', 'bin']],
      ['delete', ['delete', 'backspace', 'key']],
      ['x', ['x', 'close', 'delete']],
    ]);
    expect(ranked(lines, 'delete').map(([id, score]) => [id, score])).toEqual([
      ['trash', 90],
      ['x', 90],
      ['eraser', 90],
      ['delete', 80],
    ]);
    const both = set([
      ['bin', ['bin', 'trash']],
      ['trash', ['trash', 'bin']],
    ]);
    // 1 name (trash) and 1 meaning (bin, tagged trash): meaning leads.
    expect(ranked(both, 'trash').map(([id, score]) => [id, score])).toEqual([
      ['bin', 90],
      ['trash', 80],
    ]);
  });

  it("an icon definition the set's map names comes first", () => {
    const lines = set([['trash', ['trash', 'delete']]]);
    lines.data.icons.push({
      id: 'x',
      export: 'XIcon',
      words: ['x', 'close'],
    });
    lines.data.map = {close: 'x'};
    expect(ranked(lines, 'close')[0]).toEqual(['x', 100, 'definition "close"']);
  });

  it('an icon matches the words of every definition it is mapped to, after its own words', () => {
    // The data file lists only the icon's own name; `delete`'s words
    // (trash, bin, discard) and its name come from the definition.
    const lines = set([
      ['basket', ['basket']],
      ['pile', ['pile', 'discard']],
    ]);
    lines.data.map = {delete: 'basket'};
    expect(ranked(lines, 'bin')).toEqual([['basket', 90, 'word "bin"']]);
    // The icon's own tag ranks before a definition word.
    expect(ranked(lines, 'discard').map(([id]) => id)).toEqual([
      'pile',
      'basket',
    ]);
    // The record still shows the icon's own words.
    expect(rankIcons([lines], 'bin')[0].words).toEqual(['basket']);
  });
});

describe('icon.detail', () => {
  it('reads one icon with every variant import and the envelope package', async () => {
    const result = await icon('glyphs/trash', {cwd});
    expect(result.type).toBe('icon.detail');
    if (result.type !== 'icon.detail') return;
    expect(result.package).toBe('@acme/glyphs');
    expect(result.data.variants).toEqual([
      {
        variant: 'solid',
        module: '@acme/glyphs',
        export: 'TrashSolidIcon',
        import: "import {TrashSolidIcon} from '@acme/glyphs';",
      },
    ]);
    expect((await icon('@acme/glyphs/glyphs/x', {cwd})).type).toBe(
      'icon.detail',
    );
  });

  it('an unknown set or icon is ERR_NOT_FOUND with suggestions', async () => {
    await expect(icon('nope/trash', {cwd})).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
    });
    const error = await icon('glyphs/trashcan', {cwd}).catch(e => e);
    expect(error.suggestions[0].name).toBe('glyphs/trash');
    await expect(icon('glyphs/trashcan', {cwd})).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      suggestions: expect.arrayContaining([
        expect.objectContaining({name: 'glyphs/trash'}),
      ]),
    });
  });
});

describe('icon.list', () => {
  it('lists each set with how many icon definitions its map covers', async () => {
    const result = await icon(undefined, {cwd, list: true});
    if (result.type !== 'icon.list') throw new Error(result.type);
    expect(result.data).toMatchObject({
      status: 'selected',
      projectSet: '@acme/glyphs/glyphs',
      withdrawn: [],
    });
    const [set] = result.data.sets;
    expect(set).toMatchObject({
      name: 'glyphs',
      package: '@acme/glyphs',
      license: 'MIT',
      iconCount: 4,
      default: {variant: 'outline'},
      variants: ['outline', 'solid'],
      project: true,
    });
    expect(set.coverage.builtIn.mapped).toBe(2);
    expect(set.coverage.builtIn.total).toBe(ICON_NAMES.length);
    expect(set.coverage.builtIn.missing).toContain('chevronDown');
    expect(set.coverage.builtIn.missing).not.toContain('close');
    expect(set.coverage.astryx.total).toBeGreaterThan(ICON_NAMES.length);
    expect(set.coverage.own).toEqual([]);
  });

  it('refuses --set and --limit with one icon, which they would not change', async () => {
    for (const options of [{set: 'glyphs'}, {limit: 2}]) {
      await expect(
        icon('glyphs/trash', {cwd, ...options}),
      ).rejects.toMatchObject({code: 'ERR_INVALID_OPTION'});
    }
  });

  it('refuses a query with --list and no query without it', async () => {
    await expect(icon('x', {cwd, list: true})).rejects.toMatchObject({
      code: 'ERR_INVALID_OPTION',
      message: '--list and a query cannot be used together',
    });
    await expect(icon('', {cwd})).rejects.toMatchObject({
      code: 'ERR_MISSING_ARGUMENT',
    });
  });
});

describe('a withdrawn set, named', () => {
  it('search --set, detail, use, and list say it is withdrawn and why, not that no set has the name', async () => {
    const dir = writeIconSetProject(path.join(tmp, 'withdrawn'), {
      packages: [{}, {name: '@acme/lines', data: '{nope'}],
      config: {experimental: {iconSet: 'lines'}},
    });
    const withdrawn =
      /Icon set "lines" is installed but withdrawn: .*not valid JSON/;
    await expect(icon('close', {cwd: dir, set: 'lines'})).rejects.toMatchObject(
      {code: 'ERR_NOT_FOUND', message: expect.stringMatching(withdrawn)},
    );
    await expect(icon('lines/x', {cwd: dir})).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      message: expect.stringMatching(withdrawn),
    });
    await expect(iconUse('lines', {cwd: dir})).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      message: expect.stringMatching(withdrawn),
    });
    const listed = await icon(undefined, {cwd: dir, list: true});
    if (listed.type !== 'icon.list') throw new Error(listed.type);
    expect(listed.data.status).toBe('withdrawn');
    expect(listed.data.reason).toMatch(
      /names "lines", which is installed but withdrawn: .*not valid JSON/,
    );
    // A name no installed set has, valid or withdrawn, still says so.
    await expect(icon('close', {cwd: dir, set: 'nope'})).rejects.toMatchObject({
      message: expect.stringMatching(/No installed icon set named "nope"/),
    });
  });
});

describe('every entry point that names a set reports it the same way (FR17)', () => {
  /** @type {string} */
  let app;
  /** @type {string} */
  let authored;
  beforeEach(() => {
    app = writeIconSetProject(path.join(tmp, 'entry-app'), {
      packages: [{}, {name: '@acme/lines', data: '{nope'}],
    });
    // A package being authored with one valid set and one withdrawn one.
    authored = path.join(tmp, 'entry-pkg', 'glyphs');
    writeIconPackage(authored);
    const broken = path.join(authored, 'icon-sets', 'lines');
    fs.mkdirSync(broken, {recursive: true});
    fs.copyFileSync(
      path.join(authored, 'icon-sets', 'glyphs', 'glyphs.doc.mjs'),
      path.join(broken, 'lines.doc.mjs'),
    );
    fs.writeFileSync(
      path.join(broken, 'lines.doc.mjs'),
      fs
        .readFileSync(path.join(broken, 'lines.doc.mjs'), 'utf8')
        .replace('"name": "glyphs"', '"name": "lines"'),
    );
    fs.writeFileSync(path.join(broken, 'lines.icons.json'), '{nope');
  });

  /** @type {Array<[string, 'installed' | 'authored', (cwd: string, set: string) => Promise<unknown>]>} */
  const ENTRY_POINTS = [
    [
      'a query with --set',
      'installed',
      (dir, set) => icon('close', {cwd: dir, set}),
    ],
    [
      '--set with --all-icons',
      'installed',
      (dir, set) => icon(undefined, {cwd: dir, set, allIcons: true}),
    ],
    ['<set>/<id>', 'installed', (dir, set) => icon(`${set}/x`, {cwd: dir})],
    ['use', 'installed', (dir, set) => iconUse(set, {cwd: dir})],
    [
      'map --set',
      'authored',
      (dir, set) => iconMap('close', 'x', {cwd: dir, set}),
    ],
    [
      'add --set',
      'authored',
      (dir, set) =>
        iconAdd('XIcon', {
          cwd: dir,
          set,
          from: './icons/x.js',
          definition: 'close',
        }),
    ],
    [
      'new-definition --set',
      'authored',
      (dir, set) =>
        iconNewDefinition('binIt', {
          cwd: dir,
          set,
          description: 'Put something in the bin.',
          words: ['bin'],
        }),
    ],
  ];

  it.each(ENTRY_POINTS)('%s: a missing set', async (_label, kind, run) => {
    await expect(
      run(kind === 'installed' ? app : authored, 'nope'),
    ).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      message:
        kind === 'installed'
          ? 'No installed icon set named "nope"'
          : 'No icon set named "nope" in this package',
    });
  });

  it.each(ENTRY_POINTS)('%s: a withdrawn set', async (_label, kind, run) => {
    await expect(
      run(kind === 'installed' ? app : authored, 'lines'),
    ).rejects.toMatchObject({
      code: 'ERR_NOT_FOUND',
      message: expect.stringMatching(
        kind === 'installed'
          ? /^Icon set "lines" is installed but withdrawn: .*not valid JSON/u
          : /^Icon set "lines" is in this package but withdrawn: .*not valid JSON/u,
      ),
    });
  });
});

describe('partial matches answer only when nothing better does (FR6)', () => {
  /** @param {string} query */
  const ids = async query => {
    const result = await icon(query, {cwd, set: 'glyphs'});
    if (result.type !== 'icon.search') throw new Error(result.type);
    return result.data.matches.map(match => [match.id, match.score]);
  };

  it('leaves out a partial match when a word starts with the query', async () => {
    // `se` starts `search`, and is only inside `house` (home).
    const found = await ids('se');
    expect(found.map(([id]) => id)).toContain('search');
    expect(found.map(([id]) => id)).not.toContain('home');
    expect(found.every(([, score]) => Number(score) >= 60)).toBe(true);
  });

  it('answers with partial matches when nothing scores 60 or more', async () => {
    // `ouse` starts no word; it is inside `house`.
    const found = await ids('ouse');
    expect(found).toEqual([['home', 40]]);
  });
});

describe('a word matches whole words (FR6)', () => {
  /** @param {Array<{id: string, words?: string[]}>} icons @param {Record<string, string>} [map] */
  const setOf = (icons, map = {}) =>
    /** @type {any} */ ({
      name: 'brand',
      package: '@acme/brand-icons',
      data: {
        schemaVersion: 1,
        module: '@acme/brand-icons',
        icons: icons.map(each => ({
          export: `${each.id.replace(/(^|-)(\w)/gu, (_, __, c) => c.toUpperCase())}Icon`,
          words: each.id.split('-'),
          ...each,
        })),
        map,
      },
    });
  /** @param {any} set @param {string} query */
  const answer = (set, query) =>
    answeringMatches(rankIcons([set], query)).map(each => each.id);

  it('never offers a longer word that only starts with the query beside a whole-word answer', () => {
    const set = setOf([
      {id: 'star'},
      {id: 'chevron-left-stack', words: ['chevron', 'start']},
      {id: 'house', words: ['house', 'home', 'start']},
    ]);
    expect(answer(set, 'star')).toEqual(['star']);
    // With no whole-word answer, a word start still answers.
    expect(answer(setOf([{id: 'house', words: ['start']}]), 'star')).toEqual([
      'house',
    ]);
  });

  it('ranks the whole id first when the query is its plural', () => {
    const set = setOf([{id: 'ai-stars'}, {id: 'star'}, {id: 'stars-shine'}]);
    const ranked = rankIcons([set], 'stars');
    expect(ranked[0]).toMatchObject({id: 'star', score: 90});
    expect(answer(set, 'stars')).toEqual(['star', 'ai-stars', 'stars-shine']);
    expect(
      rankIcons([setOf([{id: 'stars'}, {id: 'star-off'}])], 'star')[0].id,
    ).toBe('stars');
  });

  it('meets a plural and its singular as the same word', () => {
    const set = setOf([{id: 'ai-stars'}, {id: 'start-flag'}]);
    expect(answer(set, 'star')).toEqual(['ai-stars']);
    expect(answer(setOf([{id: 'star'}]), 'stars')).toEqual(['star']);
  });

  it('leaves out the words that only phrase a query', () => {
    const set = setOf([{id: 'house'}, {id: 'arrow-right'}], {home: 'house'});
    expect(answer(set, 'go home')).toEqual(['house']);
    expect(answer(set, 'the home icon')).toEqual(['house']);
    // A query of filler words alone is read as written.
    expect(answer(set, 'go')).toEqual([]);
  });

  it('scores a query as typed before it leaves out filler words, so an exact name keeps its score', () => {
    const set = setOf([
      {id: 'arrow-up-to-line'},
      {id: 'arrow-up'},
      {id: 'line'},
      {id: 'a-arrow-down'},
      {id: 'arrow-down'},
      {id: 'house'},
    ]);
    const top = (/** @type {string} */ query) => rankIcons([set], query)[0];
    expect(top('arrow up to line')).toMatchObject({
      id: 'arrow-up-to-line',
      score: 90,
    });
    expect(answer(set, 'arrow up to line')).toEqual(['arrow-up-to-line']);
    expect(top('a arrow down')).toMatchObject({id: 'a-arrow-down', score: 90});
    expect(answer(set, 'a arrow down')).toEqual(['a-arrow-down']);
    // With no exact answer as typed, the filler words still drop.
    expect(answer(set, 'go house')).toEqual(['house']);
  });

  it('never matches a letter or two inside a word', () => {
    const set = setOf([{id: 'box'}, {id: 'text'}, {id: 'next-page'}]);
    expect(answer(set, 'x')).toEqual([]);
    expect(answer(set, 'ex')).toEqual([]);
    // Three letters still find a part of a word.
    expect(answer(set, 'ext')).toEqual(['next-page', 'text']);
  });
});