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

package/CMS_INFRASTRUCTURE.md

@@ -0,0 +1,370 @@
+# CMS Component Mapping Infrastructure
+
+This document describes the CMS component mapping infrastructure extracted from the Point.me marketing-site project into the core-ui package.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+  - [Core Concepts](#core-concepts)
+  - [File Structure](#file-structure)
+- [Usage Guide](#usage-guide)
+  - [1. Create Your Renderer Configuration](#1-create-your-renderer-configuration)
+  - [2. Use CmsContent with Your Configuration](#2-use-cmscontent-with-your-configuration)
+  - [3. Use UnusedChecker for Development](#3-use-unusedchecker-for-development)
+- [Configuration Composition](#configuration-composition)
+  - [Preview Mode Configuration](#preview-mode-configuration)
+  - [Environment-Specific Configurations](#environment-specific-configurations)
+  - [Embedded Context Configuration](#embedded-context-configuration)
+- [Type System](#type-system)
+  - [BaseCmsConfig](#basecmsconfig)
+  - [CmsRendererConfig](#cmsrendererconfig)
+  - [Context Types](#context-types)
+- [Development Features](#development-features)
+  - [Unknown Type Warnings](#unknown-type-warnings)
+  - [Generic Fallbacks](#generic-fallbacks)
+  - [Type Safety](#type-safety)
+- [Benefits Over Ad-Hoc Rendering](#benefits-over-ad-hoc-rendering)
+- [Migration from Marketing-Site](#migration-from-marketing-site)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+  - [CmsContent Props](#cmscontent-props)
+- [Future Enhancements](#future-enhancements)
+
+## Overview
+
+The infrastructure provides a type-safe, extensible system for mapping CMS content types to React components. It supports:
+
+- **Component/Collection Mapping**: Registry pattern for routing content types to renderers
+- **Embedding System**: Components can be rendered in embedded contexts (like rich text)
+- **Generic Fallbacks**: Automatic fallback rendering for unmapped types
+- **Development Utilities**: Warnings for unused props and rendering errors
+
+## Architecture
+
+### Core Concepts
+
+1. **Content Routing**: `CmsContent` receives an array of mixed content types and routes each to the appropriate renderer
+2. **Type Mapping**: `ComponentMap` and `CollectionMap` define which React components render which content types
+3. **Embedded Rendering**: Components can be rendered in embedded contexts (like rich text)
+
+### File Structure
+
+```
+packages/core-ui/src/
+├── components/
+│   ├── CmsComponent.tsx        # Component type router
+│   ├── CmsCollection.tsx       # Collection type router
+│   ├── CmsContent.tsx          # Main content renderer
+│   ├── GenericComponent.tsx    # Fallback component renderer
+│   └── GenericCollection.tsx   # Fallback collection renderer
+├── embeddable/
+│   ├── EmbeddableContext.ts    # Context types for embedded rendering
+│   ├── BuildEmbed.tsx          # Factory functions for embeddable components
+│   └── EmbeddableMaps.ts       # Type definitions for embeddable maps
+└── utils/
+    ├── componentUtils.ts       # Related content fetching
+    └── UnusedChecker.tsx       # Development warning utility
+```
+
+## Usage Guide
+
+### 1. Create Your Renderer Configuration
+
+The recommended approach is to create a single `CmsRendererConfig` object that bundles all your renderer maps and options:
+
+```tsx
+import { createCmsRendererConfig } from "@se-studio/core-ui";
+import type { MyProjectConfig } from "./types";
+
+// Import your component renderers
+import { HeroComponent } from "@/components/Hero";
+import { CTAComponent } from "@/components/CTA";
+import { ContentBlock } from "@/components/ContentBlock";
+
+// Import your collection renderers
+import { FAQCollection } from "@/components/FAQCollection";
+import { RelatedArticles } from "@/components/RelatedArticles";
+
+// Import special renderers (optional)
+import { VisualRenderer } from "@/components/VisualRenderer";
+import { InternalLinkRenderer } from "@/components/InternalLinkRenderer";
+
+/**
+ * Main CMS renderer configuration for the project.
+ * Create this once and reuse it throughout your app.
+ */
+export const rendererConfig = createCmsRendererConfig<MyProjectConfig>({
+  componentMap: {
+    "Hero": HeroComponent,
+    "CTA": CTAComponent,
+    "Content Block": ContentBlock,
+  },
+  collectionMap: {
+    "FAQs": FAQCollection,
+    "Related Articles": RelatedArticles,
+  },
+  // Optional: external components, visuals, links
+  externalComponentMap: {
+    "Contact Form": ContactFormRenderer,
+  },
+  visualComponentRenderer: VisualRenderer,
+  internalLinkRenderer: InternalLinkRenderer,
+  buildInformation,
+});
+```
+
+### 2. Use CmsContent with Your Configuration
+
+```tsx
+import { CmsContent } from "@se-studio/core-ui";
+import { rendererConfig } from "@/cms/rendererConfig";
+
+export function PageRenderer({ page }) {
+  const pageContext = {
+    pageLink: { slug: page.slug, title: page.title },
+  };
+
+  return (
+    <CmsContent
+      rendererConfig={rendererConfig}
+      pageContext={pageContext}
+      contents={page.contents}
+    />
+  );
+}
+```
+
+**Benefits of this approach:**
+- **Clean API**: Only 3 props instead of 7+ individual props
+- **Single source of truth**: All renderer configuration in one place
+- **Easy to extend**: Add new renderer types without touching every CmsContent call
+- **Type-safe**: Full TypeScript support with generics
+- **Composable**: Create variants with `mergeCmsRendererConfig()`
+
+### HtmlComponent entries
+
+Contentful **HTML component** entries (`type: 'HtmlComponent'`) render through `HtmlComponent` inside `CmsContent` and `CmsEmbeddedContent`. `customJs` runs inside an IIFE with a per-instance `hcRoot` (safe to place more than one scripted HtmlComponent on a page). Optional config:
+
+- **`htmlComponentFullWidthClassName`** — Tailwind (or other) classes applied when the entry has `fullWidth: true`. If unset, a built-in viewport-breakout default is used; override per project to match your grid.
+
+Hero entries (`isHero: true`) are ordered **first** within each content array for both React output and markdown/search extraction. `markdownContent` and `excludeFromSearch` control what `MarkdownConverter` emits for search indexing.
+
+### 3. Use UnusedChecker for Development
+
+Catch unused CMS properties that aren't being rendered:
+
+```tsx
+import { UnusedChecker } from "@se-studio/core-ui";
+
+export const MyComponent = ({ information, contentContext }) => {
+  const { heading, body, links, ...unused } = information;
+
+  return (
+    <UnusedChecker
+      componentName="MyComponent"
+      unused={unused}
+      showWarnings={true}
+    >
+      <div>
+        <h2>{heading}</h2>
+        <p>{body}</p>
+      </div>
+    </UnusedChecker>
+  );
+};
+```
+
+## Configuration Composition
+
+The `mergeCmsRendererConfig()` utility allows you to create specialized configurations from a base config:
+
+### Preview Mode Configuration
+
+```tsx
+import { mergeCmsRendererConfig } from "@se-studio/core-ui";
+
+const baseConfig = createCmsRendererConfig({ ... });
+
+// Preview config: use buildInformation with isProduction: false to show errors
+export const previewConfig = mergeCmsRendererConfig(baseConfig, {
+  buildInformation: { ...baseConfig.buildInformation, isProduction: false },
+});
+
+// Use in preview routes
+<CmsContent rendererConfig={previewConfig} ... />
+```
+
+### Environment-Specific Configurations
+
+```tsx
+const productionConfig = createCmsRendererConfig({
+  buildInformation: { ...buildInfo, isProduction: true },
+  componentMap: { ... },
+  collectionMap: { ... },
+});
+
+const developmentConfig = mergeCmsRendererConfig(productionConfig, {
+  buildInformation: { ...buildInfo, isProduction: false },
+});
+
+export const rendererConfig =
+  process.env.NODE_ENV === 'production'
+    ? productionConfig
+    : developmentConfig;
+```
+
+### Embedded Context Configuration
+
+```tsx
+// Different component map for embedded contexts
+const embeddedConfig = mergeCmsRendererConfig(baseConfig, {
+  componentMap: {
+    ...baseConfig.componentMap,
+    "Hero": EmbeddedHeroComponent, // Use simplified version
+  },
+});
+```
+
+## Type System
+
+### BaseCmsConfig
+
+Projects must extend `BaseCmsConfig` to define their CMS-specific types:
+
+```tsx
+import type { BaseCmsConfig } from "@se-studio/core-data-types";
+
+export interface MyProjectConfig extends BaseCmsConfig {
+  ComponentType: "Hero" | "CTA" | "Content Block";
+  CollectionType: "FAQs" | "Related Articles";
+  ExternalComponentType: "ContactForm" | "Newsletter";
+  ColourName: "red" | "blue" | "green";
+  // ... other type overrides
+}
+```
+
+### CmsRendererConfig
+
+The main configuration type that bundles all renderer maps and helpers:
+
+```tsx
+interface CmsRendererConfig<TConfig extends CmsRendererTypes> {
+  buildInformation: IBuildInformation;
+  componentMap: ComponentMap<TConfig>;
+  embeddedComponentMap: EmbeddedComponentMap<TConfig>;
+  collectionMap: CollectionMap<TConfig>;
+  embeddedCollectionMap: EmbeddedCollectionMap<TConfig>;
+  externalComponentMap: ExternalComponentMap<TConfig>;
+  embeddedExternalComponentMap: EmbeddedExternalComponentMap<TConfig>;
+  visualComponentRenderer: VisualComponentRenderer;
+  internalLinkRenderer: InternalLinkRenderer;
+  /** Optional: block RTF embeds for Internal link (vs inline `internalLinkRenderer`). */
+  embeddedBlockInternalLinkRenderer?: EmbeddedBlockInternalLinkRenderer;
+  /** Required for Contentful live preview. Pass from app cms-server so components avoid importing cms-server. */
+  previewHelpers: PreviewHelpers;
+  /** Helpers for collections that fetch data (getRelatedArticles, getAllArticleLinks, etc.). Pass from cms-server. */
+  fetchHelpers: FetchHelpers;
+  defaultComponentRenderer: ComponentRenderer<any>;
+  defaultCollectionRenderer: CollectionRenderer<any>;
+  customContentMap?: Partial<...>;
+  processText?: (text: string, contentContext?: IContentContext) => React.ReactNode;
+}
+```
+
+**Entry `meta` JSON:** Page, article, template, and related types have an optional Long text `meta` field (pretty JSON). Converters merge `template → type → entry → variant` onto `model.meta`. `buildStructuredDataContext` exposes it as `{{meta.key}}` in schema templates. Visible copy interpolates **only** `{{meta.path}}` (not full Mustache), then any site `processText` (`{{phone}}`). Use `parseMeta` / `mergeMeta` / `resolvedMeta` from `@se-studio/core-data-types` when adding `meta` to a site-only type (e.g. HSD location).
+
+Error panels (unknown types, render errors) are shown when `!buildInformation.isProduction`.
+
+**Block vs inline internal links:** Rich text `BLOCKS.EMBEDDED_ENTRY` for Internal link routes through `CmsEmbeddedContent`. Set `embeddedBlockInternalLinkRenderer` when block embeds should look different from inline links (e.g. CTA). If omitted, the block still renders using `internalLinkRenderer` inside the embed position wrapper.
+
+**Preview and fetch helpers:** Components and collections in the registration chain must **not** import from the app's `cms-server` (that causes a circular dependency). Instead they use `getPreviewFieldProps(rendererConfig, id, fieldId)` and `getPreviewResponsiveVisualFieldProps(rendererConfig, id, 'visual', 'mobileVisual')` from `@se-studio/core-ui`, and `rendererConfig.fetchHelpers` for data. The app passes `previewHelpers` (and optionally `fetchHelpers`) on the config. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
+
+**Visibility enforcement:** `createAppHelpers` enforces two visibility rules via `buildInformation`:
+
+- **`hidden` entities:** Entity fetchers (`getPageWithErrors`, `getArticleWithErrors`, etc.) return `null` data when the entity has `hidden === true` in production. Callers treat `null` as `notFound()`. In non-production environments, hidden entities are returned normally so content authors can preview them.
+- **`indexed` filtering:** Link fetchers (`getAllPageLinks`, `getAllArticleLinks`, etc.) exclude entries with `indexed === false` by default. Pass `{ allowUnindexed: true }` (via `LinkFetchOptions`) to include them. This applies in all environments. `filterRelatedArticles`, `getRelatedPeople`, and `getRelatedTags` apply the same rule on auto-filled slots.
+- **Link-shaped UI and revalidation:** Collection `contents` link refs (person, article, tag) provide **selection and order only**. `getRelatedArticles`, `getRelatedPeople`, and `getRelatedTags` always resolve display fields from `getAll*Links` listing fetches (`article`, `person`, `tag` cache tags). Entity detail routes use entity fetches (`article#slug`, etc.). Do not render portraits, titles, or hrefs from embedded page-include link objects in collection renderers.
+- **Full-list article filtering (`getAllArticleLinks`):** Pass article filter criteria directly: `articleTypeSlugs`/`articleTypeIds`, `tagSlugs`/`tagIds`, `tagType*`, `authorSlugs`/`authorIds` + `strictAuthorMatch: true` (hard filter for person pages), `before`/`after`, `excludeArticleIds`, `count`. The wrapper in `createAppHelpers` runs the base list through `filterRelatedArticles` (after indexed filtering). Use for News Grids / Publications Lists / ArticleFilter collections that need the *complete* matching set (client-side search UI, "latest N" on indexes, person-scoped lists). See also `getRelatedArticles` for limited related sets driven by collection `links`.
+- **Related Articles tag criteria (`getRelatedArticles`):** Tag filters are taken from tag links in the collection `links` or `contents`. When none are set, `applyFallbackCriteria` uses `pageContext.tag.id` (tag index pages), then `pageContext.article.tags` (article detail pages). Explicit CMS tag links always win. When `tagIds` reach `filterRelatedArticles`, articles must match at least one tag (OR semantics).
+- **`buildPageMetadata`** calls `notFound()` when `model.hidden === true` in production, providing a second safety net at the metadata layer.
+
+### Context Types
+
+- `IPageContext`: Page-level context (`page`, `article`, `articleType`, `tag`, `person`, `customType`, plus optional app keys and `[key: string]: unknown` for `prepare*` hook data). See `@se-studio/core-ui/server` `createRouteHandlers` optional `prepare*` callbacks: they shallow-merge `pageContext` **before** canonical route keys, so loaded models cannot be overridden by the hook.
+- `IContentContext`: Content-level context (current, previous, next content). **`contentContext.pageContext`** is the same object passed to `CmsContent`, so enrichment from `prepare*` hooks is available in renderers and in `processText(text, contentContext)`.
+- `IEmbeddableComponentContext<TConfig>`: Context for embedded components
+- `IEmbeddableCollectionContext<TConfig>`: Context for embedded collections
+
+## Development Features
+
+### Unknown Type Warnings
+
+When not in production (`!buildInformation.isProduction`), the infrastructure displays visual warnings for:
+- Unmapped component/collection types
+- Rendering errors
+- Unused CMS properties
+
+### Generic Fallbacks
+
+When a component/collection type isn't mapped:
+1. A warning is logged to console
+2. When not in production, an error panel is displayed
+3. A generic fallback renderer is used
+4. The page continues to render (no crashes)
+
+### Type Safety
+
+- Full TypeScript support with generic types
+- Development warnings catch unused properties
+
+## Benefits Over Ad-Hoc Rendering
+
+1. **Centralized Mapping**: All component mappings in one place
+2. **Reusability**: Components work in multiple contexts (full-page, embedded)
+3. **Maintainability**: Changes to component structure are caught at compile-time
+4. **Development UX**: Clear warnings for mistakes
+5. **Fallback Handling**: Pages never break from unmapped types
+
+## Migration from Marketing-Site
+
+To migrate an existing project:
+
+1. Install core-ui: `pnpm add @se-studio/core-ui`
+2. Create ComponentMap and CollectionMap
+3. Replace direct component rendering with CmsContent
+4. Use a non-production build (e.g. `buildInformation.isProduction: false`) to see error panels for missing mappings
+
+## Examples
+
+See the example apps in this monorepo for complete working implementations:
+- `apps/example-empty` – Template app in this monorepo (articles, people, tags cms-routes pattern)
+- Customer sites – See `docs/RELATED_PROJECTS.md` (e.g. SE Studio, Brightline, OM1 with alternative slug structures)
+
+## API Reference
+
+### CmsContent Props
+
+`CmsContent` accepts three props (all provided via a single `rendererConfig` plus page data):
+
+- `pageContext`: Page-level context information (e.g. `{ page }`, `{ article }`, `{ tag, customType }`, or indexes that only set `customType`). When using `createRouteHandlers`, optional `prepare*` hooks may add keys; canonical route fields always override duplicate keys from the hook.
+- `contents`: Array of content items to render (from `page.contents`, `article.contents`, etc.).
+- `rendererConfig`: A `CmsRendererConfig` object that bundles:
+  - `buildInformation` – Build config (isProduction, baseUrl, etc.). Error panels are shown when `!buildInformation.isProduction`.
+  - `componentMap`, `collectionMap`, `embeddedComponentMap`, `embeddedCollectionMap` – Maps of content types to renderers.
+  - `externalComponentMap`, `embeddedExternalComponentMap` – External/embed maps (optional).
+  - `visualComponentRenderer`, `internalLinkRenderer` – Renderers for Visual and Internal Link types.
+  - `previewHelpers` – **Required.** Preview helpers for Contentful live preview (pass from app cms-server).
+  - `fetchHelpers` – Helpers for data fetching in collections (`getRelatedArticles`, `getRelatedPeople`, `getRelatedTags`, `getAllArticleLinks`, `getAllTagLinks`, `getAllPersonLinks`, etc.). Link fetchers accept optional `LinkFetchOptions` (pass `{ allowUnindexed: true }` to include unindexed entries; pass articleType*/tag*/author* criteria for pre-filtered full lists via `getAllArticleLinks`). Import advanced filter symbols from `@se-studio/core-ui/server` when needed in server collections.
+  - `defaultComponentRenderer`, `defaultCollectionRenderer` – Fallback renderers for unmapped types.
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+
+- [ ] Async component loading for code splitting
+- [ ] Component preview mode for CMS editors
+- [ ] Performance monitoring hooks
+- [ ] Server-side rendering optimizations
+- [ ] Component analytics integration
+- [ ] Rich text node renderer registration system

package/CONSENT.md

@@ -0,0 +1,121 @@
+# Consent Management Guide
+
+Core UI integrates with [Orejime](https://github.com/empreinte-digitale/orejime), an open-source consent management manager, to provide GDPR and CCPA compliance.
+
+## Overview
+
+The consent system ensures that:
+1. Users are presented with a consent banner
+2. Cookies/Trackers are blocked until consent is given
+3. Analytics adapters only fire when allowed
+
+## Setup
+
+### 1. Configure Consent Provider
+
+Wrap your application with `ConsentProvider` and provide configuration.
+
+```tsx
+import { ConsentProvider } from '@se-studio/core-ui';
+
+const config = {
+  apps: [
+    {
+      name: 'google-tag-manager',
+      title: 'Analytics',
+      purposes: ['analytics'],
+      cookies: ['_ga', '_gid'],
+      required: false,
+      default: true,
+    },
+    {
+      name: 'marketing-cookies',
+      title: 'Marketing',
+      purposes: ['marketing'],
+      required: false,
+    }
+  ],
+  privacyPolicy: '/privacy-policy',
+};
+
+// Styling theme (optional)
+const theme = {
+  primaryColor: '#0070f3',
+  borderRadius: '8px',
+};
+
+export function AppProviders({ children }) {
+  return (
+    <ConsentProvider config={config} theme={theme}>
+      {children}
+    </ConsentProvider>
+  );
+}
+```
+
+### 2. Connect to Analytics
+
+Use `ConsentAwareAdapter` to gate analytics based on consent.
+
+```tsx
+import { ConsentAwareAdapter, GoogleTagManagerAdapter, useConsent } from '@se-studio/core-ui';
+
+function AnalyticsSetup() {
+  const { hasConsent } = useConsent();
+  
+  const adapter = useMemo(() => {
+    const base = new GoogleTagManagerAdapter({ containerId: '...' });
+    // 'google-tag-manager' matches the app name in config
+    return new ConsentAwareAdapter(base, 'google-tag-manager', hasConsent);
+  }, [hasConsent]);
+  
+  return <AnalyticsProvider adapter={adapter}>...</AnalyticsProvider>;
+}
+```
+
+## Styling
+
+Orejime styles can be customized via CSS variables or the `theme` prop.
+
+### Using Theme Prop
+
+```tsx
+<ConsentProvider 
+  theme={{
+    fontFamily: 'Inter, sans-serif',
+    primaryColor: '#ff0000',
+    backgroundColor: '#ffffff'
+  }}
+>
+```
+
+### Using CSS Variables
+
+In your global CSS:
+
+```css
+:root {
+  --orejime-color-primary: #ff0000;
+  --orejime-border-radius: 4px;
+  --orejime-z-index: 50;
+}
+```
+
+## Hook API
+
+The `useConsent` hook provides access to consent state.
+
+```tsx
+import { useConsent } from '@se-studio/core-ui';
+
+function MyComponent() {
+  const { hasConsent, showConsentModal, resetConsent } = useConsent();
+
+  return (
+    <div>
+      {hasConsent('analytics') && <AnalyticsDashboard />}
+      <button onClick={showConsentModal}>Cookie Settings</button>
+    </div>
+  );
+}
+```