@mui/internal-docs-infra/pipeline/enhanceCodeTypes/createElements.mjs

MUI Infra - internal documentation creation tools.

/**
 * Creates a link element wrapping the given children.
 * When `tagName` is provided, emits a custom component element with `name` property.
 * Otherwise, emits a standard `<a>` element.
 */
export function createLinkElement(href, children, identifier, className, tagName) {
  if (tagName) {
    return {
      type: 'element',
      tagName,
      properties: className && className.length > 0 ? {
        href,
        name: identifier,
        className
      } : {
        href,
        name: identifier
      },
      children
    };
  }
  return {
    type: 'element',
    tagName: 'a',
    properties: className && className.length > 0 ? {
      href,
      className
    } : {
      href
    },
    children
  };
}

/**
 * Creates a prop ref element wrapping the given children.
 *
 * When `isDefinition` is true, the property is the canonical definition site:
 * emits a `<span id="...">` (or custom component with `id` instead of `href`).
 * Otherwise, it's a reference: emits an `<a href="...">` (or custom component with `href`).
 */
export function createPropRefElement(anchor, children, ownerName, propPath, isDefinition, className, tagName) {
  // Strip leading "#" for id attributes — href="#foo" targets id="foo"
  const idValue = anchor.startsWith('#') ? anchor.slice(1) : anchor;
  if (tagName) {
    const properties = isDefinition ? {
      id: idValue,
      name: ownerName,
      prop: propPath
    } : {
      href: anchor,
      name: ownerName,
      prop: propPath
    };
    if (className && className.length > 0) {
      properties.className = className;
    }
    return {
      type: 'element',
      tagName,
      properties,
      children
    };
  }
  if (isDefinition) {
    const properties = {
      id: idValue,
      'data-name': ownerName,
      'data-prop': propPath
    };
    if (className && className.length > 0) {
      properties.className = className;
    }
    return {
      type: 'element',
      tagName: 'span',
      properties,
      children
    };
  }
  const properties = {
    href: anchor,
    'data-name': ownerName,
    'data-prop': propPath
  };
  if (className && className.length > 0) {
    properties.className = className;
  }
  return {
    type: 'element',
    tagName: 'a',
    properties,
    children
  };
}

/**
 * Creates a HAST element for a function parameter reference.
 *
 * When a custom tag is provided (`typeParamRefComponent`), emits that element with
 * `name` (owner) and `param` (parameter name) attributes.
 * Otherwise falls back to `<span id>` (definition) or `<a href>` (reference).
 */
export function createParamRefElement(anchor, children, ownerName, paramName, isDefinition, className, tagName) {
  const idValue = anchor.startsWith('#') ? anchor.slice(1) : anchor;
  if (tagName) {
    const properties = isDefinition ? {
      id: idValue,
      name: ownerName,
      param: paramName
    } : {
      href: anchor,
      name: ownerName,
      param: paramName
    };
    if (className && className.length > 0) {
      properties.className = className;
    }
    return {
      type: 'element',
      tagName,
      properties,
      children
    };
  }
  if (isDefinition) {
    const properties = {
      id: idValue,
      'data-name': ownerName,
      'data-param': paramName
    };
    if (className && className.length > 0) {
      properties.className = className;
    }
    return {
      type: 'element',
      tagName: 'span',
      properties,
      children
    };
  }
  const properties = {
    href: anchor,
    'data-name': ownerName,
    'data-param': paramName
  };
  if (className && className.length > 0) {
    properties.className = className;
  }
  return {
    type: 'element',
    tagName: 'a',
    properties,
    children
  };
}

/**
 * Creates a HAST element for a tracked literal value reference.
 *
 * When a custom tag is provided (`typeValueRefComponent`), emits that element with
 * `value` (the literal value string) and `name` (the variable/expression name) attributes.
 * Otherwise falls back to `<span data-value="...">`.
 *
 * When `refs` is provided, a JSON-serialized map of variable names to type-ref
 * anchors is attached (attribute `refs` or `data-refs`).
 */
export function createValueRefElement(value, children, name, className, tagName, refs) {
  if (tagName) {
    const properties = {
      value,
      name
    };
    if (refs && Object.keys(refs).length > 0) {
      properties.refs = JSON.stringify(refs);
    }
    if (className && className.length > 0) {
      properties.className = className;
    }
    return {
      type: 'element',
      tagName,
      properties,
      children
    };
  }
  const properties = {
    'data-value': value,
    'data-name': name
  };
  if (refs && Object.keys(refs).length > 0) {
    properties['data-refs'] = JSON.stringify(refs);
  }
  if (className && className.length > 0) {
    properties.className = className;
  }
  return {
    type: 'element',
    tagName: 'span',
    properties,
    children
  };
}