@se-studio/core-ui 0.0.0-next16-20260822103555

package/dist/utils/buildPageMetadata.js

@@ -0,0 +1,218 @@
+import { getPrimaryArticleAuthor, } from '@se-studio/core-data-types';
+import { notFound } from 'next/navigation';
+const DEFAULT_SITE_GENERATOR = {
+    name: 'Something Else',
+    url: 'https://www.se.studio',
+};
+/**
+ * Returns the path with locale prefix for non-default locales.
+ * Default locale gets the path unchanged (no prefix). Use for internal links and sitemap.
+ *
+ * @param path - Locale-neutral path (e.g. '/about/')
+ * @param locale - Current locale code (e.g. 'es-US')
+ * @param localeConfig - Optional; when absent, returns path unchanged
+ * @returns Path with locale prefix when locale is not default (e.g. '/es-US/about/')
+ */
+export function getLocalizedPath(path, locale, localeConfig) {
+    if (!localeConfig || locale === localeConfig.defaultLocale) {
+        return path;
+    }
+    const normalized = path.startsWith('/') ? path : `/${path}`;
+    return `/${locale}${normalized}`;
+}
+/**
+ * Formats the meta generator content string (single tag; Next.js does not support multiple generators).
+ * Returns `undefined` when `siteGenerator` is `null` so callers can omit the field.
+ */
+export function formatSiteGeneratorContent(siteGenerator) {
+    if (siteGenerator === null) {
+        return undefined;
+    }
+    if (typeof siteGenerator === 'string') {
+        return siteGenerator;
+    }
+    const name = siteGenerator?.name ?? DEFAULT_SITE_GENERATOR.name;
+    const url = siteGenerator?.url ?? DEFAULT_SITE_GENERATOR.url;
+    return url ? `${name} (${url})` : name;
+}
+/**
+ * Resolves HTML author metadata: primary CMS article author, else site default.
+ * Only meaningful when the model includes article author fields (article `generateMetadata` routes).
+ */
+export function resolveMetadataAuthors(model, { customerName, baseUrl }) {
+    const primaryAuthor = getPrimaryArticleAuthor(model);
+    const authorName = primaryAuthor?.name ?? primaryAuthor?.title;
+    if (authorName) {
+        return [
+            {
+                name: authorName,
+                ...(primaryAuthor?.href ? { url: `${baseUrl}${primaryAuthor.href}` } : {}),
+            },
+        ];
+    }
+    return [{ name: customerName, url: baseUrl }];
+}
+/**
+ * Builds Next.js metadata object from CMS page model.
+ *
+ * Generates comprehensive SEO metadata including:
+ * - Title and description
+ * - Open Graph tags for social sharing
+ * - Twitter Card metadata
+ * - Canonical URL
+ * - Robots directives (index/follow based on production mode)
+ * - Featured image for OG/Twitter
+ *
+ * @param model - Page model from CMS (must include title, description, featuredImage, indexed, hidden)
+ * @param path - URL path for the page (e.g., '/about-us'); when localeAlternates is set, this is the path for the current locale
+ * @param buildInfo - Build configuration (baseUrl, environment flags, customer info)
+ * @param _parent - Next.js parent metadata resolver (unused, for API compatibility)
+ * @param markdownAlternate - When true, adds link rel="alternate" type="text/markdown" for the .md version
+ * @param localeAlternates - Optional map of locale code to full path for hreflang (e.g. { 'en-US': '/about/', 'es-US': '/es-US/about/' })
+ * @returns Next.js Metadata object ready for use in page metadata exports
+ * @throws Calls `notFound()` from `next/navigation` when `model.hidden` is `true` and
+ *   `isProduction` is `true`. This aborts rendering and returns a 404 response.
+ *
+ * @example
+ * ```tsx
+ * import { buildPageMetadata } from '@se-studio/core-ui';
+ *
+ * export async function generateMetadata({ params }): Promise<Metadata> {
+ *   const page = await contentfulPageRest(config, params.slug);
+ *   return buildPageMetadata(
+ *     page,
+ *     `/${params.slug}`,
+ *     {
+ *       baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
+ *       isProduction: process.env.NODE_ENV === 'production',
+ *       isDevelopment: process.env.NODE_ENV === 'development',
+ *       customerName: 'My Company',
+ *     },
+ *     undefined
+ *   );
+ * }
+ * ```
+ */
+export function buildPageMetadata(model, path, { baseUrl, isProduction, customerName, applicationName, localeConfig, ogImagePath, siteGenerator, }, _parent, markdownAlternate, localeAlternates) {
+    if (isProduction && model.hidden === true) {
+        notFound();
+    }
+    const { title, description, featuredImage, indexed: indexedValue } = model;
+    const indexed = isProduction ? indexedValue : false;
+    const featuredImageId = featuredImage?.id;
+    const ogBase = ogImagePath ?? '/og';
+    const opengraphImageUrl = featuredImageId ? `${ogBase}/${featuredImageId}.jpg` : undefined;
+    const languages = localeAlternates && Object.keys(localeAlternates).length > 0
+        ? { ...localeAlternates }
+        : undefined;
+    if (languages && localeConfig && localeAlternates) {
+        const defUrl = localeAlternates[localeConfig.defaultLocale];
+        const firstKey = Object.keys(localeAlternates)[0];
+        const xDefault = defUrl ?? (firstKey ? localeAlternates[firstKey] : undefined);
+        if (xDefault) {
+            languages['x-default'] = xDefault;
+        }
+    }
+    const generator = formatSiteGeneratorContent(siteGenerator);
+    const result = {
+        metadataBase: new URL(baseUrl),
+        applicationName: applicationName ?? customerName,
+        authors: resolveMetadataAuthors(model, { customerName, baseUrl }),
+        ...(generator !== undefined && { generator }),
+        appleWebApp: {
+            title: applicationName ?? customerName,
+        },
+        alternates: {
+            canonical: path,
+            ...(languages && { languages }),
+            ...(markdownAlternate && {
+                types: {
+                    'text/markdown': path === '/' || path === '' ? '/index.md' : `${path.replace(/\/$/, '')}.md`,
+                },
+            }),
+        },
+        robots: {
+            index: indexed !== false,
+            follow: indexed !== false,
+        },
+        title,
+        description,
+        twitter: {
+            card: 'summary_large_image',
+            title,
+            description: description ?? undefined,
+            images: opengraphImageUrl,
+        },
+        openGraph: {
+            type: 'website',
+            url: path,
+            title,
+            description: description ?? undefined,
+            images: opengraphImageUrl,
+        },
+        other: {
+            urlUsed: baseUrl,
+            context: process.env.CONTEXT ?? 'no context',
+        },
+    };
+    return result;
+}
+/**
+ * Utility function to calculate title and description for various content types.
+ *
+ * This provides a standard way to generate SEO text for resource index pages,
+ * topic pages, and individual articles. Projects can use this in their
+ * metadata generation logic.
+ *
+ * @param params - Objects representing the context (article, tag, articleType, customType)
+ * @returns Object with title and description strings
+ */
+function articleTypeDisplayName(articleType) {
+    return articleType.name ?? articleType.title;
+}
+function customTypeDisplayName(customType) {
+    return customType.name ?? customType.title;
+}
+function tagTopicLabel(tag) {
+    return tag.name?.toLowerCase() ?? tag.title.toLowerCase();
+}
+function tagListingDescription(tag, fallback) {
+    const cms = tag.description?.trim();
+    return cms || fallback;
+}
+export function calculateTitleAndDescription({ articleType, customType, tag, person, article, }) {
+    if (person) {
+        return { title: person.title, description: person.description };
+    }
+    if (article) {
+        return { title: article.title, description: article.description, subtitle: article.subtitle };
+    }
+    if (tag && articleType) {
+        const typeName = articleTypeDisplayName(articleType);
+        return {
+            title: `${tag.title} — ${typeName}`,
+            description: tagListingDescription(tag, `Browse the latest ${typeName.toLowerCase()} resources related to ${tagTopicLabel(tag)}.`),
+        };
+    }
+    if (tag && customType) {
+        const typeName = customTypeDisplayName(customType);
+        return {
+            title: `${tag.title} — All resources`,
+            description: tagListingDescription(tag, `Browse the latest ${typeName.toLowerCase()} resources related to ${tagTopicLabel(tag)}.`),
+        };
+    }
+    if (tag) {
+        return {
+            title: tag.title,
+            description: tagListingDescription(tag, tag.description ?? ''),
+        };
+    }
+    if (articleType) {
+        return { title: articleType.title, description: articleType.description };
+    }
+    if (customType) {
+        return { title: customType.title, description: customType.description };
+    }
+    return { title: '', description: '' };
+}
+//# sourceMappingURL=buildPageMetadata.js.map

package/dist/utils/buildPageMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPageMetadata.js","sourceRoot":"","sources":["../../src/utils/buildPageMetadata.ts"],"names":[],"mappings":"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"}

package/dist/utils/cn.d.ts

@@ -0,0 +1,29 @@
+import { type ClassValue } from 'clsx';
+/**
+ * Utility function for merging Tailwind CSS classes.
+ *
+ * Combines clsx for conditional class names with tailwind-merge to intelligently
+ * merge Tailwind classes, resolving conflicts by keeping the last conflicting class.
+ *
+ * @param inputs - Variable number of class name inputs (strings, objects, arrays)
+ * @returns Merged class name string
+ *
+ * @example
+ * ```tsx
+ * import { cn } from '@se-studio/core-ui';
+ *
+ * // Basic usage
+ * cn('text-lg', 'font-bold') // 'text-lg font-bold'
+ *
+ * // Conditional classes
+ * cn('text-lg', isActive && 'text-blue-500') // 'text-lg text-blue-500' or 'text-lg'
+ *
+ * // Resolving conflicts
+ * cn('text-lg', 'text-sm') // 'text-sm' (last one wins)
+ *
+ * // With Tailwind classes
+ * cn('p-4', 'p-2') // 'p-2' (conflict resolved)
+ * ```
+ */
+export declare function cn(...inputs: ClassValue[]): string;
+//# sourceMappingURL=cn.d.ts.map

package/dist/utils/cn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../../src/utils/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,MAAM,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}

package/dist/utils/cn.js

@@ -0,0 +1,32 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+/**
+ * Utility function for merging Tailwind CSS classes.
+ *
+ * Combines clsx for conditional class names with tailwind-merge to intelligently
+ * merge Tailwind classes, resolving conflicts by keeping the last conflicting class.
+ *
+ * @param inputs - Variable number of class name inputs (strings, objects, arrays)
+ * @returns Merged class name string
+ *
+ * @example
+ * ```tsx
+ * import { cn } from '@se-studio/core-ui';
+ *
+ * // Basic usage
+ * cn('text-lg', 'font-bold') // 'text-lg font-bold'
+ *
+ * // Conditional classes
+ * cn('text-lg', isActive && 'text-blue-500') // 'text-lg text-blue-500' or 'text-lg'
+ *
+ * // Resolving conflicts
+ * cn('text-lg', 'text-sm') // 'text-sm' (last one wins)
+ *
+ * // With Tailwind classes
+ * cn('p-4', 'p-2') // 'p-2' (conflict resolved)
+ * ```
+ */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}
+//# sourceMappingURL=cn.js.map

package/dist/utils/cn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.js","sourceRoot":"","sources":["../../src/utils/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,IAAI,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,EAAE,CAAC,GAAG,MAAoB;IACxC,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/utils/componentUtils.d.ts

@@ -0,0 +1,82 @@
+import 'server-only';
+import { type BaseConverterContext, type CmsResponse, type ContentfulConfig, type FetchOptions, type IContentfulCollection } from '@se-studio/contentful-rest-api';
+import { type BaseCollectionContent, type IArticleLink, type IContentContext, type IPersonLink, type ITagLink } from '@se-studio/core-data-types';
+/**
+ * Controls how {@link getRelatedArticles} turns CMS collection links/contents + pageContext
+ * into {@link RelatedArticlesOptions} for {@link filterRelatedArticles}.
+ *
+ * Direct callers of `filterRelatedArticles` / `getAllArticleLinks` already pass full options;
+ * this policy only affects the CMS-collection helper path.
+ */
+export interface RelatedArticlesFallbackPolicy {
+    /**
+     * When true, author IDs from `pageContext.person` or explicit CMS person links are passed
+     * with `strictAuthorMatch: true` (hard filter — only that person's articles).
+     * @default true
+     */
+    strictAuthorWhenPersonCriteria: boolean;
+    /**
+     * When true, if author IDs are still empty on an article page, inject the current article's
+     * authors as soft `authorIds` (+5 ranking boost in `filterRelatedArticles`).
+     * When false (default), article-page related lists rank by tag overlap then publish date only.
+     * @default false
+     */
+    boostCurrentArticleAuthors: boolean;
+    /**
+     * When true, empty `tagIds` fall back to `pageContext.tag` then the current article's tags.
+     * @default true
+     */
+    fallbackTagsFromPageContext: boolean;
+    /**
+     * When true, empty `articleTypeIds` fall back to `pageContext.articleType` or the current
+     * article's type.
+     * @default true
+     */
+    fallbackArticleTypeFromPageContext: boolean;
+    /**
+     * When true (default), ambient tags from `pageContext.article.tags` ignore tags that are not
+     * display-eligible: `show === false` / tag type show false, `hidden === true`, or
+     * `indexed === false`. Explicit CMS tag criteria always included.
+     * `pageContext.tag` (tag index page) is always used when present.
+     * @default true
+     */
+    excludeHiddenTagsFromArticleFallback: boolean;
+}
+/** Multi-customer-safe defaults for {@link RelatedArticlesFallbackPolicy}. */
+export declare const DEFAULT_RELATED_ARTICLES_FALLBACK_POLICY: RelatedArticlesFallbackPolicy;
+/**
+ * Merge a partial policy with package defaults.
+ */
+export declare function resolveRelatedArticlesFallbackPolicy(partial?: Partial<RelatedArticlesFallbackPolicy> | null): RelatedArticlesFallbackPolicy;
+type FetchArticleLinksFn = (options: FetchOptions) => Promise<CmsResponse<IArticleLink[]>>;
+type FetchTagLinksFn = (options: FetchOptions) => Promise<CmsResponse<ITagLink[]>>;
+/**
+ * Generic helper to get related articles for a collection.
+ *
+ * Curated article refs in `contents` provide IDs and order only; display data is always
+ * resolved from `contentfulAllArticleLinks` (or injected `fetchArticleLinks`) so the
+ * `article` cache tag revalidates when entries are published.
+ *
+ * @param policy - How CMS + pageContext map to filter options. Defaults to
+ *   {@link DEFAULT_RELATED_ARTICLES_FALLBACK_POLICY}. Partial policies are merged with defaults.
+ */
+export declare function getRelatedArticles<T extends BaseCollectionContent>(information: IContentfulCollection<T>, contentContext: IContentContext, converterContext: BaseConverterContext, config: ContentfulConfig, count: number | undefined, options: FetchOptions, fetchArticleLinks?: FetchArticleLinksFn, policy?: Partial<RelatedArticlesFallbackPolicy> | null): Promise<CmsResponse<IArticleLink[]>>;
+/**
+ * Generic helper to get related people for a collection.
+ *
+ * Curated person refs in `contents` provide IDs and order only; display data is always
+ * resolved from `contentfulAllPersonLinks` so the `person` cache tag revalidates on publish.
+ */
+export declare function getRelatedPeople<T extends BaseCollectionContent>(information: IContentfulCollection<T>, contentContext: IContentContext, converterContext: BaseConverterContext, config: ContentfulConfig, count: number, options: FetchOptions, fetchPersonLinks?: (options: FetchOptions) => Promise<CmsResponse<IPersonLink[]>>): Promise<CmsResponse<IPersonLink[]>>;
+/**
+ * Generic helper to get related tags for a collection.
+ *
+ * Curated tag refs in `contents` provide IDs and order only; display data is always
+ * resolved from `contentfulAllTagLinks` so the `tag` cache tag revalidates on publish.
+ *
+ * When `contents` has no tag picks, falls back to `pageContext.tag` then the current
+ * article's tags (article detail pages). When neither is set, auto-fills from the tag listing.
+ */
+export declare function getRelatedTags<T extends BaseCollectionContent>(information: IContentfulCollection<T>, contentContext: IContentContext, converterContext: BaseConverterContext, config: ContentfulConfig, count: number, options: FetchOptions, fetchTagLinks?: FetchTagLinksFn): Promise<CmsResponse<ITagLink[]>>;
+export {};
+//# sourceMappingURL=componentUtils.d.ts.map

package/dist/utils/componentUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentUtils.d.ts","sourceRoot":"","sources":["../../src/utils/componentUtils.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,oBAAoB,EAEzB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAIrB,KAAK,YAAY,EAEjB,KAAK,qBAAqB,EAG3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,KAAK,qBAAqB,EAE1B,KAAK,YAAY,EAEjB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,QAAQ,EAKd,MAAM,4BAA4B,CAAC;AAGpC;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,8BAA8B,EAAE,OAAO,CAAC;IAExC;;;;;OAKG;IACH,0BAA0B,EAAE,OAAO,CAAC;IAEpC;;;OAGG;IACH,2BAA2B,EAAE,OAAO,CAAC;IAErC;;;;OAIG;IACH,kCAAkC,EAAE,OAAO,CAAC;IAE5C;;;;;;OAMG;IACH,oCAAoC,EAAE,OAAO,CAAC;CAC/C;AAmBD,8EAA8E;AAC9E,eAAO,MAAM,wCAAwC,EAAE,6BAMtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,CAAC,EAAE,OAAO,CAAC,6BAA6B,CAAC,GAAG,IAAI,GACtD,6BAA6B,CAK/B;AA6JD,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;AAC3F,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,qBAAqB,EACtE,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,EACrC,cAAc,EAAE,eAAe,EAC/B,gBAAgB,EAAE,oBAAoB,EACtC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,YAAY,EACrB,iBAAiB,CAAC,EAAE,mBAAmB,EACvC,MAAM,CAAC,EAAE,OAAO,CAAC,6BAA6B,CAAC,GAAG,IAAI,GACrD,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAiGtC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,qBAAqB,EACpE,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,EACrC,cAAc,EAAE,eAAe,EAC/B,gBAAgB,EAAE,oBAAoB,EACtC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,GAChF,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAuCrC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,qBAAqB,EAClE,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,EACrC,cAAc,EAAE,eAAe,EAC/B,gBAAgB,EAAE,oBAAoB,EACtC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,aAAa,CAAC,EAAE,eAAe,GAC9B,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,CAsDlC"}