Skip to content

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

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

/**
 * @file `component.list` leaf — the grouped component listing.
 *
 * @input  coreDir + list options (category filter, detail level, doc language)
 * @output ONE `component.list` envelope whose `data.detail`
 *         ('names' | 'compact' | 'full') tags the payload depth and
 *         `data.components` holds the grouped map (core + integrations +
 *         back-compat externals).
 * @position api/component/list (projection leaf; routed by component.mjs)
 */

import {
  CORE_PACKAGE,
  discoverComponents,
  discoverExternalComponentsGrouped,
  discoverValidIntegrationComponents,
  familyMember,
  findComponentReadme,
  findExternalComponentDoc,
  resolveImportPath,
  resolveIntegrationImportPath,
} from '../../../foundation/discovery/component-discovery.mjs';
import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {AstryxError} from '../../error.mjs';
import {
  loadComponentDoc,
  loadComponentReplacements,
  loadIntegrationsSafely,
  withOwnership,
} from '../_adapter.mjs';

/**
 * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
 * @typedef {import('../component.type.mjs').ComponentListEntry} ComponentListEntry
 * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
 */

/**
 * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
 * same way (`withOwnership`) so list and detail agree.
 * @param {{name: string, docsDir: string}} ext
 * @param {string} name
 * @param {string} coreDir
 * @param {{zh: boolean, lang: string|null}} docOpts
 * @returns {Promise<string>}
 */
async function legacyImport(ext, name, coreDir, docOpts) {
  const docPath = findExternalComponentDoc(ext.docsDir, name);
  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
  let docs = {};
  if (docPath && docPath.endsWith('.doc.mjs')) {
    try {
      docs = await loadComponentDoc(docPath, docOpts);
    } catch {
      // Keep list resilient; validation owns malformed docs.
    }
  }
  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
}

/**
 * A full Core ComponentDoc list entry, naming the package that owns it.
 * @param {any} doc
 */
const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});

/**
 * The full-level entry for a component documented as a member of its family's
 * doc (VStack in Stack's doc): a component doc built from the member's own
 * entry, under its own name, display name and import, shaped like every other
 * full entry. Null when the doc is the component's own.
 * @param {any} docs
 * @param {string} name
 * @param {string} coreDir
 * @returns {any}
 */
function memberEntry(docs, name, coreDir) {
  const member = familyMember(docs, name);
  if (!member) return null;
  return {
    name,
    package: CORE_PACKAGE,
    displayName: member.displayName ?? name,
    ...(docs.group ? {group: docs.group} : {}),
    ...(docs.category ? {category: docs.category} : {}),
    usage: member.usage ?? {description: member.description ?? ''},
    props: member.props ?? [],
    ...(member.examples ? {examples: member.examples} : {}),
    ...(docs.theming ? {theming: docs.theming} : {}),
    import: resolveImportPath(coreDir, name),
  };
}

/**
 * The entry for a Core slot an integration component replaces
 * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
 * its package, and the import `component <Name>` reports for it.
 * @param {import('../../../foundation/discovery/component-replacement.mjs').ActiveComponentReplacement} replacement
 * @param {'names'|'compact'|'full'} detail
 * @param {{zh: boolean, dense: boolean, lang: string|null}} docOpts
 * @returns {Promise<any>}
 */
async function replacementEntry(replacement, detail, {zh, dense, lang}) {
  const {integration} = replacement;
  /** @type {any} */
  let docs = null;
  try {
    docs = await loadComponentDoc(
      replacement.docPath,
      detail === 'full' ? {zh, lang, dense} : {zh, lang},
    );
  } catch {
    // Keep list resilient; validation owns malformed integration docs.
  }
  const importPath = resolveIntegrationImportPath(
    {
      exportsMap: integration.__packageExports,
      packageDir: integration.__packageDir,
      docPath: replacement.docPath,
      packageName: replacement.package,
    },
    replacement.name,
    docs?.import,
  );
  if (detail === 'names') {
    return {name: replacement.name, package: replacement.package, import: importPath};
  }
  if (detail === 'compact') {
    return {
      name: replacement.name,
      package: replacement.package,
      description: docs?.usage?.description || docs?.description || '',
      import: importPath,
    };
  }
  if (docs == null) {
    return {name: replacement.name, package: replacement.package, description: ''};
  }
  const {package: _owner, ...doc} = docs;
  return {
    name: doc.name ?? replacement.name,
    package: replacement.package,
    ...doc,
    import: importPath,
  };
}

/**
 * Build the `component.list` envelope. The list taxonomy is collapsed: all
 * three detail levels emit ONE `component.list` type; the depth rides in
 * `data.detail` and the grouped map in `data.components`.
 * @param {string} coreDir
 * @param {object} opts
 * @param {string} opts.cwd
 * @param {string} [opts.category] - Filter to a single category (group key).
 * @param {'full'|'compact'|'brief'} opts.detail
 * @param {boolean} opts.zh
 * @param {boolean} opts.dense
 * @param {string|null} opts.lang
 * @returns {Promise<ComponentListResponse>}
 */
export async function componentList(
  coreDir,
  {cwd, category, detail, zh, dense, lang},
) {
  const components = discoverComponents(coreDir);
  // An active integration replacement takes its Core component's slot in
  // every list view (spec:AST-035 FR11); the Core original stays reachable
  // with `component <Name> --package @astryxdesign/core`.
  const loadedIntegrations = await loadIntegrationsSafely(cwd);
  const replacements = await loadComponentReplacements(
    coreDir,
    loadedIntegrations,
  );
  const docOpts = {zh, dense, lang};

  if (category) {
    const match = Object.entries(components).find(
      ([key]) => key.toLowerCase() === category.toLowerCase(),
    );
    if (!match) {
      throw new AstryxError(
        `Unknown category "${category}"`,
        Object.keys(components).map(k => ({name: k, reason: 'valid category'})),
        ERROR_CODES.ERR_UNKNOWN_CATEGORY,
      );
    }

    if (detail === 'compact') {
      /** @type {ComponentBriefEntry[]} */
      const entries = [];
      for (const comp of match[1]) {
        const replacement = replacements.forTarget(comp);
        if (replacement) {
          entries.push(await replacementEntry(replacement, 'compact', docOpts));
          continue;
        }
        const readme = findComponentReadme(coreDir, comp);
        if (readme && readme.endsWith('.doc.mjs')) {
          try {
            const docs = await loadComponentDoc(readme, {zh, lang});
            entries.push({
              name: comp,
              package: CORE_PACKAGE,
              description:
                familyMember(docs, comp)?.description ||
                docs.usage?.description ||
                docs.description ||
                '',
              import: resolveImportPath(coreDir, comp),
            });
          } catch {
            entries.push({
              name: comp,
              package: CORE_PACKAGE,
              description: '',
              import: resolveImportPath(coreDir, comp),
            });
          }
        } else {
          entries.push({
            name: comp,
            package: CORE_PACKAGE,
            description: '',
            import: resolveImportPath(coreDir, comp),
          });
        }
      }
      return {
        type: 'component.list',
        data: {detail: 'compact', components: {[match[0]]: entries}},
      };
    }

    if (detail === 'full') {
      /** @type {any[]} */
      const entries = [];
      for (const comp of match[1]) {
        const replacement = replacements.forTarget(comp);
        if (replacement) {
          entries.push(await replacementEntry(replacement, 'full', docOpts));
          continue;
        }
        const readme = findComponentReadme(coreDir, comp);
        if (readme && readme.endsWith('.doc.mjs')) {
          try {
            const docs = await loadComponentDoc(readme, {zh, lang, dense});
            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
          } catch {
            entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
          }
        } else {
          entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
        }
      }
      return {
        type: 'component.list',
        data: {detail: 'full', components: {[match[0]]: entries}},
      };
    }

    // Default: brief — package-qualified object list for the category.
    // Pre-1.0 JSON contract: members are {name, package} objects, not bare
    // strings, so consumers can disambiguate ownership.
    return {
      type: 'component.list',
      data: {
        detail: 'names',
        components: {
          [match[0]]: await Promise.all(
            match[1].map(n => {
              const replacement = replacements.forTarget(n);
              return replacement
                ? replacementEntry(replacement, 'names', docOpts)
                : {name: n, package: CORE_PACKAGE};
            }),
          ),
        },
      },
    };
  }

  // All components — merge core + external packages with grouped subcategories
  if (detail === 'compact') {
    /** @type {Record<string, ComponentBriefEntry[]>} */
    const result = {};
    for (const [cat, comps] of Object.entries(components)) {
      result[cat] = [];
      for (const comp of comps) {
        const replacement = replacements.forTarget(comp);
        if (replacement) {
          result[cat].push(await replacementEntry(replacement, 'compact', docOpts));
          continue;
        }
        const readme = findComponentReadme(coreDir, comp);
        if (readme && readme.endsWith('.doc.mjs')) {
          try {
            const docs = await loadComponentDoc(readme, {zh, lang});
            result[cat].push({
              name: comp,
              package: CORE_PACKAGE,
              description:
                familyMember(docs, comp)?.description ||
                docs.usage?.description ||
                docs.description ||
                '',
              import: resolveImportPath(coreDir, comp),
            });
          } catch {
            result[cat].push({
              name: comp,
              package: CORE_PACKAGE,
              description: '',
              import: resolveImportPath(coreDir, comp),
            });
          }
        } else {
          result[cat].push({
            name: comp,
            package: CORE_PACKAGE,
            description: '',
            import: resolveImportPath(coreDir, comp),
          });
        }
      }
    }
    return {
      type: 'component.list',
      data: {detail: 'compact', components: result},
    };
  }

  if (detail === 'full') {
    /** @type {Record<string, any[]>} */
    const result = {};
    for (const [cat, comps] of Object.entries(components)) {
      result[cat] = [];
      for (const comp of comps) {
        const replacement = replacements.forTarget(comp);
        if (replacement) {
          result[cat].push(await replacementEntry(replacement, 'full', docOpts));
          continue;
        }
        const readme = findComponentReadme(coreDir, comp);
        if (readme && readme.endsWith('.doc.mjs')) {
          try {
            const docs = await loadComponentDoc(readme, {zh, lang, dense});
            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
          } catch {
            result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
          }
        } else {
          result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
        }
      }
    }
    return {type: 'component.list', data: {detail: 'full', components: result}};
  }

  // Default: brief — package-qualified object list (core + integrations).
  // Pre-1.0 JSON contract: each group's members are {name, package} objects.
  /** @type {Record<string, ComponentListEntry[]>} */
  const listData = {};
  for (const [cat, comps] of Object.entries(components)) {
    listData[cat] = await Promise.all(
      comps.map(n => {
        const replacement = replacements.forTarget(n);
        return replacement
          ? replacementEntry(replacement, 'names', docOpts)
          : {name: n, package: CORE_PACKAGE};
      }),
    );
  }
  // A replacement is listed once, in the Core slot it took.
  const listedReplacements = new Set(
    replacements.active.map(active => `${active.package}\0${active.name}`),
  );

  // Integration components (authoritative source: loadedIntegrations).
  const seenIntegration = new Set();
  for (const integration of loadedIntegrations) {
    seenIntegration.add(integration.name);
    const {components: owned} =
      await discoverValidIntegrationComponents(integration);
    // Group integration components by their doc `group`, falling back to the
    // package name. Keys are package-qualified so they never collide with
    // core groups or each other.
    /** @type {Map<string, Array<{name: string, package: string, import?: string}>>} */
    const byGroup = new Map();
    for (const rec of owned) {
      if (listedReplacements.has(`${integration.name}\0${rec.name}`)) continue;
      const groupLabel = rec.group ?? integration.name;
      const key = `${groupLabel} (${integration.name})`;
      if (!byGroup.has(key)) byGroup.set(key, []);
      // Use the doc-authored import when present; otherwise resolve the package
      // export so list, detail, search, JSON, and human output all agree.
      const fallbackImport = resolveIntegrationImportPath(
        {
          exportsMap: integration.__packageExports,
          packageDir: integration.__packageDir,
          docPath: rec.docPath,
          packageName: integration.name,
        },
        rec.name,
      );
      let importPath = fallbackImport;
      try {
        const docs = await loadComponentDoc(rec.docPath, {zh, lang});
        importPath = resolveIntegrationImportPath(
          {
            exportsMap: integration.__packageExports,
            packageDir: integration.__packageDir,
            docPath: rec.docPath,
            packageName: integration.name,
          },
          rec.name,
          docs.import,
        );
      } catch {
        // Keep list resilient; validation owns malformed integration docs.
      }
      byGroup.get(key)?.push({
        name: rec.name,
        package: integration.name,
        import: importPath,
      });
    }
    for (const [key, members] of byGroup) {
      members.sort((a, b) => a.name.localeCompare(b.name));
      listData[key] = members;
    }
  }

  // Back-compat: node_modules-scanned external packages (pkg.astryx.docs)
  // that are NOT configured integrations. Preserves existing discovery for
  // consumers that haven't adopted the config-integration flow.
  const externals = discoverExternalPackages(cwd);
  for (const ext of externals) {
    if (seenIntegration.has(ext.name)) continue;
    const grouped = discoverExternalComponentsGrouped(ext.docsDir);
    const groupKeys = Object.keys(grouped);
    if (groupKeys.length === 0) continue;

    const hasGroups = groupKeys.some(
      k => grouped[k].length > 1 || grouped[k][0] !== k,
    );

    /** @param {string[]} names */
    const entriesFor = names =>
      Promise.all(
        names.map(async n => ({
          name: n,
          package: ext.name,
          import: await legacyImport(ext, n, coreDir, {zh, lang}),
        })),
      );

    if (hasGroups) {
      for (const [group, members] of Object.entries(grouped)) {
        listData[`${group} (${ext.name})`] = await entriesFor(members);
      }
    } else {
      const allComps = Object.values(grouped).flat().sort();
      if (allComps.length > 0) {
        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
      }
    }
  }
  return {
    type: 'component.list',
    data: {detail: 'names', components: listData},
  };
}