/**
 * Converts a string to title case for catalog option labels.
 * Splits on whitespace, hyphens, and underscores; capitalizes each word.
 * The first word is rendered as "API" when it is "api" (case-insensitive).
 *
 * @param str - The raw string to format (e.g. from config or entity data).
 * @returns The formatted label with words capitalized and joined by spaces.
 *
 * @example
 * customCatalogOptionsCasing('api_spec')           // 'API Spec'
 * customCatalogOptionsCasing('my-custom-option')  // 'My Custom Option'
 * customCatalogOptionsCasing('user name')         // 'User Name'
 * customCatalogOptionsCasing('  api   version  ') // 'API Version'
 */
export function customCatalogOptionsCasing(str: string): string {
  const trimmedStr = str.trim();
  if (!trimmedStr) return trimmedStr;

  const words = trimmedStr.split(/[\s-_]+/);

  return words
    .map((word, index) => {
      if (index === 0 && word.toLowerCase() === 'api') {
        return 'API';
      }
      return word[0].toUpperCase() + word.slice(1);
    })
    .join(' ');
}