import { useContext } from "react";
import { Meta, type MetaDescriptor, type MetaFunction, UNSAFE_FrameworkContext, useMatches } from "react-router";
import { defaultBrandTokens } from "@hivegrid/brand";
const HIVEGRID_PRODUCT_NAME = defaultBrandTokens.productName;
const TITLE_SEPARATOR = " | ";
const LEGACY_PRODUCT_NAMES = ["Application Starter", "Anwendungsstarter"] as const;
export function formatHiveGridDocumentTitle(rawTitle: unknown, configuredProductNames: readonly string[] = []): string {
if (typeof rawTitle !== "string") return HIVEGRID_PRODUCT_NAME;
const productNames = new Set(
[HIVEGRID_PRODUCT_NAME, ...LEGACY_PRODUCT_NAMES, ...configuredProductNames].map((name) => name.trim().toLocaleLowerCase()).filter(Boolean)
);
let pageTitle = rawTitle.trim();
// Strip only known product suffixes from the right. Page/entity names may
// legitimately contain pipes (for example "Küche | Bad") and must survive.
while (pageTitle) {
const separatorIndex = pageTitle.lastIndexOf("|");
const trailingSegment = pageTitle.slice(separatorIndex + 1).trim();
if (!productNames.has(trailingSegment.toLocaleLowerCase())) break;
pageTitle = separatorIndex >= 0 ? pageTitle.slice(0, separatorIndex).trim() : "";
}
if (!pageTitle) return HIVEGRID_PRODUCT_NAME;
return `${pageTitle}${TITLE_SEPARATOR}${HIVEGRID_PRODUCT_NAME}`;
}
export function createHiveGridMetaFunction(originalMeta?: MetaFunction): MetaFunction {
return (args) => {
const inheritedDescriptors = args.matches.at(-2)?.meta ?? [];
const loaderData = args.loaderData ?? args.data;
const loaderDescriptors = extractLoaderMetaDescriptors(loaderData);
const loaderTitle = extractLoaderTitle(loaderData);
const configuredProductNames = extractConfiguredProductNames(args);
let descriptors: MetaDescriptor[];
if (originalMeta) {
descriptors = flattenMetaDescriptors(originalMeta(args));
} else if (loaderDescriptors.length > 0) {
descriptors = loaderDescriptors;
} else {
descriptors = [...inheritedDescriptors];
}
// A route without `meta` can still expose the page title used by the shell
// and breadcrumbs. Prefer that title over the inherited parent title.
const titleOverride = !originalMeta && loaderTitle ? loaderTitle : undefined;
const fallbackTitle = loaderTitle ?? findDocumentTitle(inheritedDescriptors) ?? HIVEGRID_PRODUCT_NAME;
return enforceHiveGridTitle(descriptors, fallbackTitle, configuredProductNames, titleOverride);
};
}
/**
* React Router renders only the deepest route's metadata. This adapter keeps
* its renderer and route-level meta functions intact, but installs one title
* contract for Core, Admin, public pages and the customer portal. It also lets
* routes that already return `loaderData.title` participate without hundreds
* of repetitive `meta` exports.
*
* React Router is pinned in the workspace; the focused tests guard this small
* framework-context seam when the dependency is upgraded.
*/
export function HiveGridMeta() {
const frameworkContext = useContext(UNSAFE_FrameworkContext);
const activeRouteIds = new Set(useMatches().map((match) => match.id));
if (!frameworkContext) return ;
const routeModules = Object.fromEntries(
Object.entries(frameworkContext.routeModules).map(([routeId, routeModule]) => [
routeId,
routeModule && activeRouteIds.has(routeId)
? {
...routeModule,
meta: createHiveGridMetaFunction(routeModule.meta),
}
: routeModule,
])
) as typeof frameworkContext.routeModules;
return (
);
}
function enforceHiveGridTitle(
descriptors: readonly MetaDescriptor[],
fallbackTitle: unknown,
configuredProductNames: readonly string[],
titleOverride?: string
): MetaDescriptor[] {
const flattened = flattenMetaDescriptors(descriptors);
const explicitTitle = titleOverride ?? findDocumentTitle(flattened);
const normalizedTitle = formatHiveGridDocumentTitle(explicitTitle ?? fallbackTitle, configuredProductNames);
const normalized: MetaDescriptor[] = [];
let titleInserted = false;
for (const descriptor of flattened) {
if (isDocumentTitleDescriptor(descriptor)) {
if (!titleInserted) {
normalized.push({ title: normalizedTitle });
titleInserted = true;
}
continue;
}
normalized.push(descriptor);
}
if (!titleInserted) normalized.unshift({ title: normalizedTitle });
return normalized;
}
function extractConfiguredProductNames(args: Parameters[0]): string[] {
const rootTitle = extractLoaderTitle(args.matches[0]?.loaderData);
if (!rootTitle) return [];
const configuredProductName = rootTitle.slice(rootTitle.lastIndexOf("|") + 1).trim();
return configuredProductName ? [configuredProductName] : [];
}
function extractLoaderTitle(loaderData: unknown): string | undefined {
if (!isRecord(loaderData)) return undefined;
const directTitle = nonEmptyString(loaderData.title);
if (directTitle) return directTitle;
if (isRecord(loaderData.meta)) {
const nestedTitle = nonEmptyString(loaderData.meta.title);
if (nestedTitle) return nestedTitle;
}
return findDocumentTitle(extractLoaderMetaDescriptors(loaderData));
}
function extractLoaderMetaDescriptors(loaderData: unknown): MetaDescriptor[] {
if (!isRecord(loaderData)) return [];
for (const key of ["metatags", "metadata"] as const) {
const descriptors = flattenMetaDescriptors(loaderData[key]);
if (descriptors.length > 0) return descriptors;
}
return [];
}
function findDocumentTitle(descriptors: readonly MetaDescriptor[]): string | undefined {
let title: string | undefined;
for (const descriptor of descriptors) {
if (!isDocumentTitleDescriptor(descriptor)) continue;
title = nonEmptyString(descriptor.title) ?? title;
}
return title;
}
function isDocumentTitleDescriptor(descriptor: MetaDescriptor): descriptor is MetaDescriptor & { title: unknown } {
return !("tagName" in descriptor) && "title" in descriptor;
}
function flattenMetaDescriptors(value: unknown): MetaDescriptor[] {
if (!Array.isArray(value)) return [];
return value.flat(1).filter(isRecord) as MetaDescriptor[];
}
function nonEmptyString(value: unknown): string | undefined {
if (typeof value !== "string") return undefined;
const normalized = value.trim();
return normalized.length > 0 ? normalized : undefined;
}
function isRecord(value: unknown): value is Record {
return typeof value === "object" && value !== null && !Array.isArray(value);
}