Skip to content

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

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

import {describe, expect, it} from 'vitest';

import {isWeightsFile} from '../_adapter.mjs';
import {SHELL, stem, weighStart, weightWords} from './weights.mjs';

// A made-up table for tests only: three page templates and the app shell.
const CANDIDATES = [SHELL, 'board', 'charts', 'grid'];

/**
 * @param {Record<string, number[]>} weights per word, one value per candidate
 * @param {number[]} [bias]
 * @param {number} [step]
 * @param {number} [clip]
 */
function table(weights, bias = [0, 0, 0, 0], step = 0.5, clip = 4) {
  return {
    words: Object.keys(weights),
    bias,
    clip,
    step,
    rows: Object.values(weights).map(ws =>
      ws
        .map(w => String.fromCharCode(97 + Math.round((w + clip) / step)))
        .join(''),
    ),
  };
}

const WEIGHTS = {
  version: 1,
  candidates: CANDIDATES,
  tables: [
    table({
      [stem('kanban')]: [0, 3, 0, 0],
      [stem('existing')]: [3, 0, 0, 0],
      [stem('charts')]: [0, 0, 2, 0],
    }),
    table({[stem('cards')]: [0, 0, 0, 1]}, [0, 0, 0, 0], 1, 4),
  ],
  // three numbers per member (table 1, the ranker, table 2), then one for SHELL
  blend: [1, 0, 0, 0.5, 0, 0, 0.2, 0, 0, 0],
};
const CATALOG = [
  {name: 'board'},
  {name: 'charts'},
  {name: 'grid'},
  {name: 'top-nav'},
];

/**
 * @param {string} name
 * @param {number} score
 * @param {string} family
 */
const page = (name, score, family) => ({
  name,
  score,
  hits: 1,
  family,
  base: true,
  familyNamed: false,
  containerMatched: false,
  matched: new Set(),
});
/** A ranker output that prefers `charts`. */
const RANKED = [
  page('charts', 3, 'Charts'),
  page('grid', 1, 'Grid'),
  page('board', 0.5, 'Board'),
  page('top-nav', 0, 'Shell'),
];

describe('weighStart', () => {
  it('lets the word weights outvote the ranker', () => {
    const start = weighStart(
      'a kanban for launches',
      RANKED,
      RANKED[0],
      CATALOG,
      {
        weights: WEIGHTS,
      },
    );
    expect(start).toBe('board');
  });

  it('keeps the ranker when the words carry no weight', () => {
    const start = weighStart('something else', RANKED, RANKED[0], CATALOG, {
      weights: WEIGHTS,
    });
    expect(start).toBe('charts');
  });

  it('returns null for the app shell', () => {
    const start = weighStart('tweak the existing page', RANKED, null, CATALOG, {
      weights: WEIGHTS,
    });
    expect(start).toBeNull();
  });

  it('returns undefined without weights, so the ranker decides', () => {
    const start = weighStart('a kanban', RANKED, RANKED[0], CATALOG, {
      weights: null,
    });
    expect(start).toBeUndefined();
  });

  it('never starts from a template the project does not have', () => {
    const catalog = CATALOG.filter(t => t.name !== 'board');
    const ranked = RANKED.filter(r => r.name !== 'board');
    const start = weighStart('a kanban', ranked, ranked[0], catalog, {
      weights: WEIGHTS,
    });
    expect(start).not.toBe('board');
  });

  it("keeps the ranker's pick of a template the tables do not list", () => {
    const catalog = [...CATALOG, {name: 'fresh'}];
    const ranked = [page('fresh', 9, 'Fresh'), ...RANKED];
    const start = weighStart('a kanban', ranked, ranked[0], catalog, {
      weights: WEIGHTS,
    });
    expect(start).toBe('fresh');
  });

  describe('a template the tables do not list (cold start)', () => {
    // A made-up family the tables have never seen, described only by its own
    // descriptor, next to listed templates with descriptors of their own.
    const catalog = [
      {name: 'board', displayName: 'Kanban Board', keywords: ['kanban']},
      {name: 'charts', displayName: 'Charts', category: 'Charts - Overview'},
      {name: 'grid', displayName: 'Grid'},
      {
        name: 'gauge-fleet',
        displayName: 'Fleet Gauges',
        category: 'Gauges - Fleet',
        keywords: ['gauges', 'fleet', 'meters'],
      },
    ];

    it('starts from it when the idea names its own words', () => {
      const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];
      const start = weighStart(
        'fleet gauges with meters per kanban lane',
        ranked,
        ranked[0],
        catalog,
        {weights: WEIGHTS},
      );
      expect(start).toBe('gauge-fleet');
    });

    it('starts from it when the idea names its family first', () => {
      const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];
      const start = weighStart(
        'gauges page with a kanban board',
        ranked,
        ranked[0],
        catalog,
        {weights: WEIGHTS},
      );
      expect(start).toBe('gauge-fleet');
    });

    it("never counts a stopword from another template's keywords", () => {
      // "side" in grid's "side by side" keyword is one of search's stopwords;
      // it must not answer the idea's "sides", which is not.
      const own = [
        {name: 'board'},
        {name: 'charts'},
        {
          name: 'grid',
          displayName: 'Grid',
          keywords: ['side by side', 'orders'],
        },
        {name: 'fold', displayName: 'Folding Rows'},
      ];
      const ranked = [page('fold', 9, 'Fold'), ...RANKED];
      const start = weighStart(
        'rows on two sides with orders on cards',
        ranked,
        ranked[0],
        own,
        {weights: WEIGHTS},
      );
      expect(start).toBe('fold');
    });

    it("never counts a stopword from the idea's words", () => {
      // "basically" is one of search's stopwords and stems to "basic", the
      // word of grid's category; it must not tip the count to grid.
      const own = [
        {name: 'board'},
        {name: 'charts'},
        {name: 'grid', displayName: 'Grid', category: 'Grid - Basic'},
        {name: 'fold', displayName: 'Folding Rows'},
      ];
      const ranked = [page('fold', 9, 'Fold'), ...RANKED];
      const start = weighStart(
        'basically a grid of rows on cards',
        ranked,
        ranked[0],
        own,
        {weights: WEIGHTS},
      );
      expect(start).toBe('fold');
    });

    it('yields to the listed template whose own words the idea names more', () => {
      const ranked = [page('gauge-fleet', 9, 'Gauges'), ...RANKED];
      const start = weighStart(
        'a kanban board with a fleet column',
        ranked,
        ranked[0],
        catalog,
        {weights: WEIGHTS},
      );
      expect(start).toBe('board');
    });
  });

  it("keeps the ranker's template for an idea that asks for a new page", () => {
    const start = weighStart('the existing page', RANKED, RANKED[0], CATALOG, {
      weights: WEIGHTS,
      newPage: true,
    });
    expect(start).toBe('charts');
  });

  it('starts a new page from the shell when the ranker has no template', () => {
    const start = weighStart('the existing page', RANKED, null, CATALOG, {
      weights: WEIGHTS,
      newPage: true,
    });
    expect(start).toBeNull();
  });

  it('keeps a template the ranker placed by its frame', () => {
    const framed = {...RANKED[1], containerMatched: true};
    for (const idea of ['the existing page', 'a kanban']) {
      const start = weighStart(idea, RANKED, framed, CATALOG, {
        weights: WEIGHTS,
      });
      expect(start).toBe('grid');
    }
  });

  it('is deterministic', () => {
    const run = () =>
      weighStart('kanban charts cards', RANKED, RANKED[0], CATALOG, {
        weights: WEIGHTS,
      });
    expect(run()).toBe(run());
  });
});

describe('weightWords', () => {
  it('keeps letter words of two or more characters', () => {
    expect(weightWords('A 3-col Dashboard, v2 KPIs!')).toEqual([
      'col',
      'dashboard',
      'kpis',
    ]);
  });
});

describe('isWeightsFile', () => {
  it('accepts a well-formed file', () => {
    expect(isWeightsFile(WEIGHTS)).toBe(true);
  });

  it('rejects a file whose rows, bias or blend do not fit the candidates', () => {
    const [first, second] = WEIGHTS.tables;
    expect(isWeightsFile({...WEIGHTS, blend: [1, 2, 3]})).toBe(false);
    expect(
      isWeightsFile({...WEIGHTS, tables: [{...first, rows: ['ab']}, second]}),
    ).toBe(false);
    expect(
      isWeightsFile({...WEIGHTS, tables: [{...first, bias: [0]}, second]}),
    ).toBe(false);
    expect(isWeightsFile({version: 1})).toBe(false);
    expect(isWeightsFile(null)).toBe(false);
  });
});