Skip to content

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

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

/**
 * @file Pure views over discover sources' catalogs: which catalog packages the
 * project already has, what it could add, and the items search looks through.
 * No I/O; the adapter supplies every input.
 *
 * @position api/discover — shared by the list, detail, item, and search leaves.
 */

import {KIND_FIELDS} from './_adapter.mjs';

/**
 * @typedef {import('./_adapter.mjs').InstalledPackage} InstalledPackage
 * @typedef {import('./_adapter.mjs').CatalogResult} CatalogResult
 * @typedef {CatalogResult['packages'][number]} CatalogPackage
 * @typedef {import('../../authoring/discover/type').DiscoverKind} DiscoverKind
 */

/**
 * An item search looks through. `kind: 'package'` is a package itself.
 * @typedef {object} SearchItem
 * @property {string} package
 * @property {DiscoverKind | 'package'} kind
 * @property {string} name
 * @property {boolean} installed
 * @property {string} [title]
 * @property {string} [summary]
 * @property {string[]} [keywords]
 * @property {string} [description]
 */

/**
 * Group a version's contributions into the entry fields, one list per kind.
 * `components` is always present, like on an installed entry.
 * @param {CatalogPackage['contributions']} contributions
 * @returns {Record<string, string[]>}
 */
export function kindLists(contributions) {
  /** @type {Record<string, string[]>} */
  const lists = {components: []};
  for (const [kind, field] of KIND_FIELDS) {
    const names = contributions.filter(c => c.kind === kind).map(c => c.name);
    if (names.length > 0 || field === 'components') lists[field] = names;
  }
  return lists;
}

/**
 * Whether an entry adds at least one item of `kind`.
 * @param {Record<string, unknown>} entry
 * @param {DiscoverKind} kind
 * @returns {boolean}
 */
export function hasKind(entry, kind) {
  const field = KIND_FIELDS.find(([k]) => k === kind)?.[1];
  const values = field == null ? undefined : entry[field];
  return Array.isArray(values) && values.length > 0;
}

/**
 * Where a catalog package stands against the project. An entry the official
 * list supplied is checked against the project's own package.json
 * (`officialDeclared`); any other entry against the folder discover runs in
 * (`declared`).
 * @param {CatalogPackage} pkg
 * @param {Set<string>} installedNames
 * @param {Set<string>} declared
 * @param {Set<string>} [officialDeclared]
 * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
 */
export function catalogState(pkg, installedNames, declared, officialDeclared) {
  if (installedNames.has(pkg.package)) return {state: 'installed'};
  if (
    (pkg.official && officialDeclared ? officialDeclared : declared).has(
      pkg.package,
    )
  )
    return {state: 'declared'};
  const installedAs = pkg.aliases.find(
    name => installedNames.has(name) || declared.has(name),
  );
  if (installedAs != null) return {state: 'alias', installedAs};
  return {state: 'available'};
}

/**
 * The version a catalog package shows by default.
 * @param {CatalogPackage} pkg
 * @returns {string | undefined}
 */
export function defaultVersion(pkg) {
  return pkg.latest ?? pkg.versions[0]?.version;
}

/**
 * Project a catalog package into the entry shape installed packages use.
 * @param {CatalogPackage} pkg
 * @param {string | undefined} version
 */
export function catalogEntry(pkg, version) {
  const {components, ...others} = kindLists(pkg.contributions);
  return {
    name: pkg.package,
    package: pkg.package,
    category: pkg.package,
    components,
    ...(version ? {version} : {}),
    ...(pkg.description ? {description: pkg.description} : {}),
    ...others,
  };
}

/**
 * What the project could add: every catalog package it does not have, once per
 * integration (the first name a source lists), never an alias of one it has,
 * each with the command that adds it when `install` is given.
 * @param {CatalogResult} catalog
 * @param {InstalledPackage[]} installed
 * @param {Set<string>} declared
 * @param {{officialDeclared?: Set<string>, install?: (pkg: CatalogPackage) => string}} [options]
 */
export function availableEntries(
  catalog,
  installed,
  declared,
  {officialDeclared, install} = {},
) {
  const installedNames = new Set(installed.map(p => p.name));
  /** @type {Set<string>} */
  const integrations = new Set();
  const entries = [];
  for (const pkg of catalog.packages) {
    if (
      catalogState(pkg, installedNames, declared, officialDeclared).state !==
      'available'
    )
      continue;
    if (integrations.has(pkg.integration)) continue;
    integrations.add(pkg.integration);
    const version = defaultVersion(pkg);
    const {category: _category, ...entry} = catalogEntry(pkg, version);
    entries.push({
      ...entry,
      ...(pkg.aliases.length > 0 ? {aliases: pkg.aliases} : {}),
      source: pkg.source,
      ...(install ? {install: install(pkg)} : {}),
    });
  }
  return entries;
}

/**
 * Installed packages with the latest release a source knows for each.
 * @param {InstalledPackage[]} installed
 * @param {CatalogResult} catalog
 * @returns {Array<InstalledPackage & {latest?: string}>}
 */
export function withLatest(installed, catalog) {
  const byName = new Map(catalog.packages.map(p => [p.package, p]));
  return installed.map(pkg => {
    const latest = byName.get(pkg.name)?.latest;
    return latest ? {...pkg, latest} : pkg;
  });
}

/**
 * Everything search looks through besides installed components (which the
 * search leaf keeps resolving the way it always has): installed packages and
 * their other items, and every package the project could add with its items.
 * @param {InstalledPackage[]} installed
 * @param {CatalogResult} catalog
 * @param {Set<string>} declared
 * @param {Set<string>} [officialDeclared]
 * @returns {SearchItem[]}
 */
export function searchItems(installed, catalog, declared, officialDeclared) {
  /** @type {SearchItem[]} */
  const items = [];
  for (const pkg of installed) {
    items.push({
      package: pkg.name,
      kind: 'package',
      name: pkg.name,
      installed: true,
      ...(pkg.description ? {description: pkg.description} : {}),
    });
    for (const [kind, field] of KIND_FIELDS) {
      if (kind === 'component') continue;
      const names = /** @type {Record<string, unknown>} */ (pkg)[field];
      if (!Array.isArray(names)) continue;
      for (const name of names) {
        items.push({package: pkg.name, kind, name, installed: true});
      }
    }
  }
  const installedNames = new Set(installed.map(p => p.name));
  /** @type {Set<string>} */
  const integrations = new Set();
  for (const pkg of catalog.packages) {
    if (
      catalogState(pkg, installedNames, declared, officialDeclared).state !==
      'available'
    )
      continue;
    if (integrations.has(pkg.integration)) continue;
    integrations.add(pkg.integration);
    items.push({
      package: pkg.package,
      kind: 'package',
      name: pkg.package,
      installed: false,
      ...(pkg.description ? {description: pkg.description} : {}),
    });
    for (const c of pkg.contributions) {
      items.push({
        package: pkg.package,
        kind: c.kind,
        name: c.name,
        installed: false,
        ...(c.title ? {title: c.title} : {}),
        ...(c.summary ? {summary: c.summary} : {}),
        ...(c.keywords ? {keywords: c.keywords} : {}),
      });
    }
  }
  return items;
}