Skip to content

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

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

/**
 * @file Reading a component or hook doc for search: the compiled doc and its
 * usage guidance. Imported only by the adapter's gatherers.
 */

import {readDocView} from '../../foundation/doc-compiler/read.mjs';

/** @typedef {import('./_gather-components.mjs').Candidate} Candidate */

/**
 * A component or hook doc, compiled, or null when it cannot be read.
 * @param {string} docPath
 * @param {string} [exportName]
 * @param {'components' | 'hooks'} [root]
 * @returns {Promise<any>}
 */
export async function loadModuleDoc(
  docPath,
  exportName = 'docs',
  root = 'components',
) {
  try {
    // Support both the stamped default export and the legacy named export.
    return (
      (await readDocView(docPath, {
        root,
        loader: 'native',
        exports: ['default', exportName],
      })) ?? null
    );
  } catch {
    return null;
  }
}

/**
 * Build component candidates from core's own tree: name + keywords +
 * usage/description from the component's .doc.mjs.
 * @param {string} coreDir
 * @returns {Promise<Candidate[]>}
 */

/**
 * Usage guidance from a component doc: its feature list and its best-practice
 * advice, flattened to plain strings.
 *
 * This is where a reader's vocabulary usually lives. `Banner` calls itself "a
 * persistent message" and only its guidance names "form errors, system
 * updates, maintenance notices" — so a search for the words people actually
 * type finds nothing without it.
 *
 * @param {any} doc
 * @returns {string[]}
 */
export function guidanceFrom(doc) {
  if (!doc) return [];
  const features = Array.isArray(doc.features) ? doc.features : [];
  const practices = Array.isArray(doc.usage?.bestPractices)
    ? doc.usage.bestPractices
    : [];
  return [...features, ...practices]
    .map(entry =>
      typeof entry === 'string'
        ? entry
        : [
            entry?.title,
            entry?.text,
            entry?.description,
            entry?.do,
            entry?.dont,
          ]
            .filter(Boolean)
            .join(' '),
    )
    .filter(Boolean);
}