\n```\n\n#### CMS Showcase\n\nThe library provides a set of components and utilities to build a CMS component showcase for your project.\n\n- **`ShowcasePage`** - The main interface for selecting components and adjusting mock data.\n- **`ShowcaseRenderPage`** - The renderer component for the preview iframe.\n- **`mockFactory`** - Utilities for generating mock data from CMS registrations.\n\nSee the [CMS Showcase Infrastructure Guide](./src/showcase/README.md) for more details.\n\n### Animation & Monitoring Components\n\n#### ClientMonitor\n\nMonitors page elements for scroll-based animations and visibility tracking. Automatically tracks elements with `data-component` attributes, videos, and Lottie animations using IntersectionObserver.\n\n**Props:**\n- `defaultThreshold?` - Number (0-1) - Default intersection threshold for triggering animations (default: 0.2)\n- `enableDebug?` - Boolean - Enable debug logging in development mode (default: false)\n\n**Example:**\n```tsx\nimport { ClientMonitor } from '@se-studio/core-ui';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n \n {children}\n \n \n );\n}\n```\n\n**How it works:**\n- Automatically finds and observes all elements with `data-component` attributes\n- Tracks video elements for play/pause based on visibility\n- Tracks Lottie animation elements for play/pause based on visibility\n- Sets `data-seen=\"true\"` and `data-visible=\"true\"` attributes on elements when they enter the viewport\n- Uses scroll progress calculation for tall elements that exceed viewport height\n\n**Excluding components from animation:**\n\nTo exclude a component from animation tracking, add the `data-exclude-animation` attribute:\n\n```tsx\n\n {/* This component will not be tracked by ClientMonitor */}\n {/* It will not receive data-seen or data-visible attributes */}\n
\n```\n\n**Custom thresholds:**\n\nYou can set a custom intersection threshold for individual elements using the `data-intersection-threshold` attribute:\n\n```tsx\n\n {/* This component will trigger when 50% visible */}\n
\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Run tests\npnpm test\n\n# Run tests in watch mode\npnpm test:watch\n\n# Build the library\npnpm build\n\n# Type check\npnpm type-check\n\n# Lint\npnpm lint\n```\n\n## Tailwind Configuration\n\n### Custom Breakpoints\n\nThe library includes custom breakpoints optimized for modern responsive design:\n\n- `tablet`: 768px\n- `laptop`: 1024px\n- `desktop`: 1440px\n\nUse them in your Tailwind classes:\n\n```tsx\n\n {/* Content */}\n
\n```\n\n### Typography Utilities\n\nCustom typography styles are available:\n\n- `text-h1` - Heading 1 style\n- `text-h2` - Heading 2 style\n- `text-h3` - Heading 3 style\n- `text-h4` - Heading 4 style\n- `text-body` - Body text style\n- `text-body-sm` - Small body text\n\n## Configuration System\n\nThe package exports several configuration utilities:\n\n### createCmsRendererConfig\n\nCreates a type-safe CMS renderer configuration:\n\n```tsx\nimport { createCmsRendererConfig } from '@se-studio/core-ui';\n\nconst config = createCmsRendererConfig({\n components: {\n heroSection: HeroComponent,\n featureSection: FeatureComponent\n },\n collections: {\n cardGrid: CardGridCollection\n }\n});\n```\n\n### mergeCmsRendererConfig\n\nMerges multiple configurations (useful for environment-specific or preview mode configs):\n\n```tsx\nimport { mergeCmsRendererConfig } from '@se-studio/core-ui';\n\nconst previewConfig = mergeCmsRendererConfig(\n baseConfig,\n previewOverrides\n);\n```\n\n## API Reference\n\n### Main Exports\n\n#### Components\n- **`CmsContent`** - Main component for rendering CMS content with automatic component mapping\n- **`CmsComponent`** - Renders individual CMS components with type-based routing\n- **`CmsCollection`** - Renders CMS collections (arrays of components)\n- **`Visual`** - Optimized image/video/animation component with Next.js Image integration\n- **`RTF`** - Renders Contentful rich text with support for embedded entries and assets\n- **`UnusedChecker`** - Development utility to detect unused CMS content types\n\n#### Hooks\n- **`useAnalytics`** - Hook for accessing analytics functions (trackEvent, trackPage, trackClick)\n- **`useClickTracking`** - Hook for tracking click events with analytics\n- **`useDocumentVisible`** - Hook for tracking document visibility\n\n#### Utilities\n- **`createRobotsConfig`** - Builds `MetadataRoute.Robots` for `src/app/robots.ts` with shared production disallow defaults; configurable via `pathPrefix`, `apiPrefixes`, `disallowExtra`, `disallowOmit`, and `blockTrackingQueryParams`\n- **`buildRobotsDisallow`** - Returns the production disallow path list (for plain-text robots route handlers)\n- **`formatRobotsTxt` / `createRobotsTxtResponse`** - Plain-text robots.txt including optional Content Signals (`src/app/robots.txt/route.ts`)\n- **`resolveMarkdownNegotiationPath` / `prefersMarkdownAccept` / `htmlPathToMarkdownPath`** - Middleware helpers for `Accept: text/markdown` → existing `/{path}.md` rewrites\n- **`apiPathNeedingTrailingSlash`** - Middleware helper: rewrite bare `/api/*` → `/api/*/` when `trailingSlash: true` so MCP POST and other APIs are not 308’d\n- **`appendAgentDiscoveryLinkHeaders` / `buildAgentDiscoveryLinkValues`** - Homepage/document `Link` headers (`describedby` → `/llms.txt`, alternate markdown)\n- **`buildPageMetadata`** - Generates Next.js metadata object from CMS page model\n- **`handleCmsError`** - Error handling utility for CMS operations\n- **`getRelatedArticles`** - Fetches related articles for collections (limited sets): `contents` article refs provide IDs/order only; display data is always resolved from `contentfulAllArticleLinks` (or `getAllArticleLinks` via `createAppHelpers`) so the `article` cache tag revalidates on publish. Auto-fill uses `filterRelatedArticles`. Tag criteria come from collection tag links, or fall back to `pageContext.tag`, then the current article's tags on article detail pages. See also full-list filtering via `getAllArticleLinks` (below).\n- **`getRelatedPeople`** - Related people for collections: `contents` person refs are IDs/order only; always resolved from `contentfulAllPersonLinks` / `getAllPersonLinks` (`person` cache tag).\n- **`getRelatedTags`** - Related tags for collections: `contents` tag refs are IDs/order only; always resolved from `contentfulAllTagLinks` / `getAllTagLinks` (`tag` cache tag). Falls back to `pageContext.tag` or the current article's tags when `contents` is empty.\n- **`cn`** - Utility function for merging Tailwind CSS classes\n- **`joinCmsPathSegments`** - Join App Router catch-all CMS params into a slug, or `null` for missing/non-array params and Next.js filesystem probes (`[level1]`, `page-*.js`). Callers should `notFound()` on null.\n\n#### Server-only exports (import from `@se-studio/core-ui/server`)\n- **`createAppHelpers`** — Factory for `getAll*Links`, `getPageWithErrors`, `getRelatedArticles`, `getSitemapEntries` (when configured), etc. Wire with your converterContext + buildOptions.\n- **`filterRelatedArticles`** + **`RelatedArticlesOptions`** — Re-export of the pure article list filter/ranker (articleType/tag/author/tagType slugs+ids, strict author mode, scoring, dates, etc.). Use in collection renderers or custom full-list logic (e.g. News Grids, person-scoped Publications lists). `getAllArticleLinks(options)` on the helpers already applies these filters when you pass `articleTypeSlugs`, `strictAuthorMatch`, etc.\n- **`articleLinkToListCard`** — Maps `IArticleLink` → `IListCard` for RSC listing rows. Collection files should import this from `/server`, not the rest-api main barrel.\n- **`getRelatedArticles`** / **`getRelatedPeople`** / **`getRelatedTags`** (also re-exported here for server collections)\n- **`buildListingItems`** / **`buildListingStructuredDataContext`** — ItemList JSON-LD context for article-type, tag, and person listing pages (async CMS fetch via `getAllArticleLinks` + `filterRelatedArticles`)\n\n#### Sitemap Utilities\n- **`createSitemapXmlRouteHandler`** / **`createSitemapXmlResponse`** — GET helper for `app/sitemap.xml/route.ts` (force-dynamic + CDN no-store). Do **not** use metadata `app/sitemap.ts` on Vercel.\n- **`SITEMAP_CACHE_TAG`** / **`SITEMAP_XML_HEADERS`** — listing fetch tag (`sitemap`) and XML response headers\n- **`buildSitemap`** - Builds a Next.js sitemap from multiple async sources; calls each source in parallel, deduplicates by URL, and converts to `MetadataRoute.Sitemap`\n- **`sitemapToXml`** - Converts a `MetadataRoute.Sitemap` array to sitemap XML string for Route Handlers\n- **`generateNextSitemap`** - Converts sitemap entries to Next.js format with baseUrl normalization\n- **`deduplicateSitemapEntries`** - Deduplicates entries by URL (keeps most recent `lastModified`)\n- **`sortSitemapEntries`** - Sorts by priority then lastModified\n\n#### Types\n- **`CmsRendererConfig`** - Complete renderer configuration type\n- **`MarketingSiteSitemapConfig`** - Config for `getSitemapEntries` when using createAppHelpers (optional articlesSlug when enableArticleTypeIndex, tagsSlug, enableArticleTypeIndex, other feature flags, optional additionalSources)\n- **`AppHelpersWithSitemap`** - Return type of `createAppHelpers` when `marketingSiteSitemap` is provided; use when you need to type helpers that include `getSitemapEntries`\n- **`SitemapEntry`**, **`SitemapSource`**, **`GenerateSitemapOptions`** - Types for building custom sitemap sources\n- **`LinkFetchOptions`** - Options for all `getAll*Links` helpers (and `rendererConfig.fetchHelpers`). Article-specific keys (`articleTypeSlugs`, `tagSlugs`, `authorSlugs`, `strictAuthorMatch`, `tagType*`, `before`/`after`, `count`, `excludeArticleIds`) only affect `getAllArticleLinks` (delegated to `filterRelatedArticles` after the raw fetch + indexed filter). `pageSize` is the CDA chunk; `maxItems` (docs alias: fetch `limit`) slices this caller after a shared unbounded listing memo; `count` is the post-filter slice.\n\nFor detailed JSDoc documentation on all exports, see the TypeScript declaration files (`.d.ts`) in the package.\n\n### Sitemap Usage\n\nUse a Route Handler (`app/sitemap.xml/route.ts`), not metadata `app/sitemap.ts`. Next metadata sitemaps are static/ISR; on Vercel the CDN can keep serving HIT after the Contentful webhook calls `revalidateTag('sitemap')`. The listing fetch is still `force-cache` + the `sitemap` tag (no hourly `revalidate`), so Contentful is not hit on every request.\n\n`dynamic` and `revalidate` **must** be literals in the route file (Next.js static analysis). Do not re-export them from this package.\n\n```ts\n// app/sitemap.xml/route.ts\nimport { createSitemapXmlRouteHandler } from '@se-studio/core-ui';\nimport { baseUrl } from '@/lib/server-config';\nimport { getSitemapEntries } from '@/lib/sitemap-sources';\n\nexport const dynamic = 'force-dynamic';\nexport const revalidate = 0;\n\nexport const GET = createSitemapXmlRouteHandler({\n getEntries: () => getSitemapEntries({ includeUnindexed: false }),\n baseUrl,\n defaultPriority: 0.5,\n defaultChangeFrequency: 'monthly',\n trailingSlash: true,\n});\n```\n\nUnindexed (audit) sitemap — same helper, `includeUnindexed: true`:\n\n```ts\n// app/sitemap-unindexed.xml/route.ts\nimport { createSitemapXmlRouteHandler } from '@se-studio/core-ui';\nimport { baseUrl } from '@/lib/server-config';\nimport { getSitemapEntries } from '@/lib/sitemap-sources';\n\nexport const dynamic = 'force-dynamic';\nexport const revalidate = 0;\n\nexport const GET = createSitemapXmlRouteHandler({\n getEntries: () => getSitemapEntries({ includeUnindexed: true }),\n baseUrl,\n defaultPriority: 0.5,\n defaultChangeFrequency: 'monthly',\n trailingSlash: true,\n});\n```\n\nAdd both paths to `route-build-policy.json` `allowedDynamic`. Do not keep `app/sitemap.ts` next to `app/sitemap.xml/route.ts` — they both serve `/sitemap.xml`.\n\n### Marketing Site Sitemap (createAppHelpers)\n\nWhen using `createAppHelpers`, pass `marketingSiteSitemap` to enable `getSitemapEntries` for sites with articles, tags, and people. When provided, `getSitemapEntries` is guaranteed and correctly typed (return type is `AppHelpersWithSitemap`), so you can re-export it from a `sitemap-sources` module without type assertions.\n\n```ts\n// lib/cms-server.ts\nconst { getSitemapEntries, ... } = createAppHelpers({\n converterContext,\n getConfig: getContentfulConfig,\n buildOptions,\n marketingSiteSitemap: {\n ...(enableArticleTypeIndex && { articlesSlug: ARTICLES_SLUG }),\n tagsSlug: TAGS_SLUG,\n enableArticleTypeIndex,\n enableArticleTypeTagIndex,\n enablePeopleIndex,\n enablePerson,\n enableTag,\n enableTagsIndex,\n additionalSources: [\n () => getDrivePageSitemapEntries(), // custom content, e.g. drive pages\n ],\n },\n});\n```\n\n`additionalSources` are merged into the main sitemap only (not the unindexed sitemap). For custom content from another Contentful table, add async functions that return `SitemapEntry[]`.\n\n### `@se-studio/core-ui/server` – Route Handlers Factory\n\nThe `/server` entry point (server-only) provides `createRouteHandlers`, a factory that centralises all `generate*Page` and `generate*Metadata` functions for CMS-driven Next.js apps.\n\nEach app wires it once in `src/lib/route-handlers.ts`:\n\n```typescript\nimport 'server-only';\nimport { createRouteHandlers } from '@se-studio/core-ui/server';\nimport BasicLayout from '@/project/BasicLayout';\nimport { buildOptions, getBannersWithErrors, getPageWithErrors, ... , projectRendererConfig } from './cms-server';\nimport { buildInformation } from './converter-context';\nimport { ARTICLES_SLUG, TAGS_SLUG, PEOPLE_SLUG, articlesCustomTypeSlug,\n requireCustomTypeForArticleTypes, enableTag, enablePerson, enableTagsIndex } from './constants';\n\nexport const {\n generatePage, generatePageMetadata,\n generateArticlePage, generateArticleMetadata,\n generateArticleTypePage, generateArticleTypeMetadata,\n generateArticleTypeTagPage, generateArticleTypeTagMetadata,\n generateArticleTypesIndexPage, generateArticleTypesIndexMetadata,\n generateTagPage, generateTagMetadata,\n generateTagsIndexPage, generateTagsIndexMetadata,\n generatePersonPage, generatePersonMetadata,\n generateTeamIndexPage, generateTeamIndexMetadata,\n generateCustomTypePage, generateCustomTypeMetadata,\n buildLocaleAlternates,\n} = createRouteHandlers({\n rendererConfig: projectRendererConfig,\n buildOptions,\n buildInformation,\n getBannersWithErrors,\n getPageWithErrors,\n // ... remaining fetch helpers\n LayoutComponent: BasicLayout,\n constants: { ARTICLES_SLUG, TAGS_SLUG, PEOPLE_SLUG, articlesCustomTypeSlug,\n requireCustomTypeForArticleTypes, enableTag, enablePerson, enableTagsIndex },\n});\n```\n\nRoute files then import directly from `@/lib/route-handlers`.\n\n#### Not-found pages\n\nUse one slim root `src/app/not-found.tsx` by default:\n\n```tsx\nimport { generateNotFoundMetadata, generateSlimNotFoundPage } from '@/lib/route-handlers';\n\nexport const metadata = generateNotFoundMetadata();\n\nexport default function NotFound() {\n return generateSlimNotFoundPage();\n}\n```\n\n`generateSlimNotFoundPage` renders the configured heading and description without a CMS fetch or\n`LayoutComponent`. Next.js copies not-found component seeds into Flight responses for successful\npages, so keeping this root module slim avoids adding the full layout and CMS tree to 200-page\nresponses. `generateNotFoundPage` remains available when a site explicitly opts into the full\nCMS-backed shell.\n\n#### `CmsRouteConfig` (per-route flags)\n\nEach route passes a `CmsRouteConfig` into `generate*Page` and `generate*Metadata`. Common fields:\n\n| Field | Default | Purpose |\n|-------|---------|---------|\n| `throwOnNotFound` | (required) | When true, missing CMS entries call Next.js `notFound()` |\n| `showBreadcrumbs` | (required) | Show breadcrumb trail in layout |\n| `truncateBreadcrumbs` | (required) | Truncate long breadcrumb paths |\n| `videoEmbedDnt` | `false` | Pass `dnt: true` in analytics context for privacy-enhanced video embeds |\n| `requireArticleContent` | `true` | When `false`, `generateArticlePage` allows articles with no body components (metadata/template-only, e.g. publication posters) |\n\nExample for metadata-only article detail routes:\n\n```typescript\nexport const ARTICLE_DETAIL_ROUTE_CONFIG: CmsRouteConfig = {\n throwOnNotFound: true,\n showBreadcrumbs: true,\n truncateBreadcrumbs: true,\n requireArticleContent: false,\n};\n```\n\n#### Optional `prepare*` hooks (async `pageContext` enrichment)\n\n`RouteHandlersConfig` may include any of these optional callbacks. Each runs **after** the route’s fetch and **after** the usual “will render” guards, and **before** `CmsContent` is rendered:\n\n| Hook | Runs with |\n|------|-----------|\n| `preparePage` | `generatePage` |\n| `prepareArticlePage` | `generateArticlePage` |\n| `prepareArticleTypePage` | `generateArticleTypePage` |\n| `prepareArticleTypeTagPage` | `generateArticleTypeTagPage` |\n| `prepareArticleTypesIndexPage` | `generateArticleTypesIndexPage` |\n| `prepareTagPage` | `generateTagPage` |\n| `prepareTagsIndexPage` | `generateTagsIndexPage` |\n| `preparePersonPage` | `generatePersonPage` |\n| `prepareTeamIndexPage` | `generateTeamIndexPage` |\n| `prepareCustomTypePage` | `generateCustomTypePage` |\n\nEach hook returns `Promise`, where `pageContext` is an optional object of extra keys to merge into `CmsContent`’s `pageContext`. **Merge order:** hook keys are applied first, then the route’s canonical keys (`page`, `article`, `tag`, `articleType`, `person`, `customType` as applicable). Canonical keys **always win**, so the hook cannot replace the loaded CMS models.\n\nHook inputs mirror what that route already has (models, `errors`, `path`, `locale`, `routeConfig`, route-specific slugs). `banners` is only passed when that route’s data loader already fetches banners.\n\nRead merged values from components and rich text via `contentContext.pageContext` (and from `rendererConfig.processText(text, contentContext)` when used). Types are exported from `@se-studio/core-ui/server` (`CmsPagePreparationResult`, `PreparePageInput`, `PrepareArticlePageInput`, etc.).\n\nApps that bypass `createRouteHandlers` for a custom page should build the same `pageContext` merge locally if they need the same pattern.\n\n#### Tag index and `TAGS_SLUG` custom type\n\n`generateTagPage` / `generateTagMetadata` resolve the tag via `getTagWithErrors` (which may merge template content from the `TAGS_SLUG` entry inside the REST layer). They also call `getCustomTypeWithErrors(TAGS_SLUG)` for the shell row used in `pageContext` and metadata.\n\n- **Default (relaxed):** If `constants.tagIndexRequiresCustomType` is omitted or `false`, a tag with non-empty `contents` still renders when the shell row is missing or returns null (for example when the entry is **hidden** in production and `getCustomTypeWithErrors` strips it). In that case `pageContext.customType` may be omitted or undefined; `IPageContext.customType` is already optional.\n- **Strict (legacy):** Set `tagIndexRequiresCustomType: true` to require both the tag and a resolved shell custom type, matching the old behaviour (404 if the shell is absent).\n\nThe same flag applies to **`generateArticleTypeTagPage`** / **`generateArticleTypeTagMetadata`** for the tag shell fetched with `TAGS_SLUG`.\n\nThe `/server` entry also exports `canRenderTagIndex` and `canRenderArticleTypeTagRoute` (pure helpers used by the factory), `CmsRouteConfig`, `BreadcrumbOptions`, `toBreadcrumbOptions`, `BasicLayoutProps`, and the `prepare*`-related types (`CmsPagePreparationResult`, `PreparePageInput`, `RouteHandlersPrepareHooks`, etc.). The types (but not `createRouteHandlers`) are also re-exported from the main package entry for client-safe use where applicable.\n\n## Advanced Usage\n\nFor advanced CMS infrastructure usage, including:\n- Configuration composition patterns\n- Embeddable components\n- Context passing\n- Preview mode setup\n\nSee the [CMS Infrastructure Guide](./CMS_INFRASTRUCTURE.md).\n\n## Examples\n\nCheck out [example-empty](../../apps/example-empty) in this monorepo, or customer sites listed in [docs/RELATED_PROJECTS.md](../../docs/RELATED_PROJECTS.md), for complete implementations using core-ui features.\n\n## Learn More\n\n- [CMS Infrastructure Guide](./CMS_INFRASTRUCTURE.md) - Comprehensive guide to the CMS system\n- [Analytics Integration Guide](./ANALYTICS.md) - Analytics and GTM setup\n- [Consent Management Guide](./CONSENT.md) - GDPR/CCPA compliance setup\n- [Core Data Types](../core-data-types/README.md) - Shared TypeScript types\n- [Contentful REST API](../contentful-rest-api/README.md) - API client for Contentful\n\n## License\n\nMIT\n","readmeFilename":""}