@raven-js/glean/lib/server/components/attribution-bar.js

Glean documentation gold from your codebase - JSDoc parsing, validation, and beautiful doc generation

/**
 * @author Anonyfox <max@anonyfox.com>
 * @license MIT
 * @see {@link https://github.com/Anonyfox/ravenjs}
 * @see {@link https://ravenjs.dev}
 * @see {@link https://anonyfox.com}
 */

/**
 * @file Attribution bar component with author and contributor display.
 *
 * Renders author information with proper mailto links and contributor
 * information through Bootstrap utility classes. Optional rendering -
 * displays nothing when no attribution exists.
 */

import { html } from "@raven-js/beak";

/**
 * Render primary author information with optional email link
 * @param {any} primaryAuthor - Primary author data
 * @returns {string} HTML for primary author display
 */
function renderPrimaryAuthor(primaryAuthor) {
	if (!primaryAuthor || !primaryAuthor.name) {
		return "";
	}

	if (primaryAuthor.hasEmail && primaryAuthor.email) {
		return html`
			<span class="text-muted small">
				By <a href="mailto:${primaryAuthor.email}" class="text-decoration-none">${primaryAuthor.name}</a>
			</span>
		`;
	}

	return html`
		<span class="text-muted small">
			By ${primaryAuthor.name}
		</span>
	`;
}

/**
 * Render contributors list with proper email links
 * @param {Array<Object>} contributors - Contributors array
 * @returns {string} HTML for contributors display
 */
function renderContributors(contributors) {
	if (!Array.isArray(contributors) || contributors.length === 0) {
		return "";
	}

	const contributorLinks = contributors
		.filter((contributor) => /** @type {any} */ (contributor).name)
		.map((contributor) => {
			/** @type {any} */
			const c = contributor;
			if (c.hasEmail && c.email) {
				return html`<a href="mailto:${c.email}" class="text-decoration-none text-muted">${c.name}</a>`;
			}
			return html`<span class="text-muted">${c.name}</span>`;
		})
		.join(", ");

	if (contributorLinks) {
		return html`
			<span class="text-muted small">
				| Contributors: ${contributorLinks}
			</span>
		`;
	}

	return "";
}

/**
 * Attribution bar component displaying primary author and contributors with subtitle styling.
 *
 * Displays primary author and contributors using Bootstrap small text and muted colors.
 * Returns empty string when no attribution context exists.
 *
 * @param {import('../../extract/models/attribution.js').AttributionContext} attributionContext - Attribution context
 * @returns {string} HTML attribution bar or empty string
 *
 * @example
 * // Basic attribution bar
 * attributionBar(attributionContext);
 *
 * @example
 * // Returns empty string when no attribution
 * attributionBar(null); // → ""
 */
export function attributionBar(attributionContext) {
	if (
		!attributionContext ||
		!attributionContext.hasAttribution ||
		!attributionContext.hasAuthors
	) {
		return "";
	}

	const primaryAuthor = attributionContext.getPrimaryAuthor();
	const contributors = attributionContext.getContributors();

	const primaryAuthorHtml = renderPrimaryAuthor(primaryAuthor);
	const contributorsHtml = renderContributors(contributors);

	if (!primaryAuthorHtml && !contributorsHtml) {
		return "";
	}

	return html`
		<div class="mt-2">
			${primaryAuthorHtml}
			${contributorsHtml}
		</div>
	`;
}