@otl-core/cms-utils 1.0.0 → 1.0.4

package/dist/index.d.cts

@@ -0,0 +1,519 @@
+import { BlogCategory, ResponsiveValue, BorderConfig, ShadowConfig, ColorReference, LocalizedString, BreakpointWithBase, ResponsiveConfig, OrganizationInfo } from '@otl-core/cms-types';
+import { ClassValue } from 'clsx';
+
+/**
+ * A/B/n Variant Resolver
+ *
+ * Framework-agnostic logic for resolving multivariate content to a single
+ * variant per visitor. Uses a deterministic bucket value (float [0, 1))
+ * to ensure sticky variant assignment.
+ *
+ * This module handles resolving only -- analytics and testing evaluation
+ * happen separately downstream.
+ */
+interface VariantConfig {
+    id: string;
+    weight: number;
+}
+interface MultivariatePageContent {
+    page: unknown;
+    seo: unknown;
+    multivariate: true;
+    variants: Array<{
+        id: string;
+        weight: number;
+        sections: unknown[];
+    }>;
+}
+interface MultivariateFormBlockData {
+    definition: unknown;
+    multivariate: true;
+    variants: Array<{
+        id: string;
+        weight: number;
+        document: unknown;
+    }>;
+}
+/**
+ * Given a bucket value [0, 1) and variant weights,
+ * deterministically select a variant.
+ *
+ * The weights don't need to sum to 100 -- they are normalized.
+ * A user with a given bucket will always get the same variant
+ * for a given weight configuration.
+ */
+declare function selectVariant(bucket: number, variants: VariantConfig[]): string;
+/**
+ * Check if page content is multivariate.
+ */
+declare function isMultivariateContent(content: Record<string, unknown>): boolean;
+/**
+ * Resolve multivariate page content to a single variant's sections.
+ * Returns the selected sections array and the variant ID.
+ */
+declare function resolvePageVariant(content: MultivariatePageContent, bucket: number): {
+    sections: unknown[];
+    variantId: string;
+};
+/**
+ * Resolve multivariate blog post content to a single variant's blocks.
+ * Blog post layouts are blog-level (no variants). The post's content blocks
+ * are the variant data, returned alongside the shared layout.
+ *
+ * Mutates the content record in place: replaces "variants" with the selected "blocks".
+ */
+declare function resolveBlogPostVariant(content: Record<string, unknown>, bucket: number): void;
+/**
+ * Walk through sections/blocks and resolve any multivariate form block data.
+ * This should be called on the server before passing data to client components,
+ * so client-side FormBlock never has to deal with variant resolution.
+ */
+declare function resolveFormVariantsInSections(sections: unknown[], bucket: number): unknown[];
+
+/**
+ * Category utility functions
+ */
+
+/**
+ * Tree node with children
+ */
+interface CategoryTreeNode extends BlogCategory {
+    children: CategoryTreeNode[];
+}
+/**
+ * Builds a hierarchical tree from flat category array
+ * @param categories Flat array of categories
+ * @returns Array of root-level categories with nested children
+ */
+declare function buildCategoryTree(categories: BlogCategory[]): CategoryTreeNode[];
+/**
+ * Flattens a category tree back to a flat array
+ * @param tree Hierarchical category tree
+ * @returns Flat array of categories
+ */
+declare function flattenCategoryTree(tree: CategoryTreeNode[]): BlogCategory[];
+/**
+ * Gets the full path of a category (all ancestors)
+ * @param categoryId Category ID to get path for
+ * @param categories Flat array of all categories
+ * @param locale Locale to use for names (optional)
+ * @returns Array of categories from root to target
+ */
+declare function getCategoryPath(categoryId: string, categories: BlogCategory[], locale?: string): BlogCategory[];
+/**
+ * Gets the display name for a category in a specific locale
+ * @param category Category object
+ * @param locale Locale code (e.g., 'en', 'de-DE')
+ * @param fallbackLocale Fallback locale if primary not found
+ * @returns Display name string
+ */
+declare function getCategoryName(category: BlogCategory, locale: string, fallbackLocale?: string): string;
+/**
+ * Gets the slug for a category in a specific locale
+ * @param category Category object
+ * @param locale Locale code
+ * @param fallbackLocale Fallback locale if primary not found
+ * @returns Slug string
+ */
+declare function getCategorySlug(category: BlogCategory, locale: string, fallbackLocale?: string): string;
+/**
+ * Checks if a category is an ancestor of another category
+ * @param ancestorId Potential ancestor category ID
+ * @param descendantId Descendant category ID
+ * @param categories Flat array of all categories
+ * @returns True if ancestorId is an ancestor of descendantId
+ */
+declare function isAncestor(ancestorId: string, descendantId: string, categories: BlogCategory[]): boolean;
+/**
+ * Gets all descendants of a category (recursive)
+ * @param categoryId Parent category ID
+ * @param categories Flat array of all categories
+ * @returns Array of all descendant categories
+ */
+declare function getDescendants(categoryId: string, categories: BlogCategory[]): BlogCategory[];
+/**
+ * Finds a category by slug in a specific locale
+ * @param slug Slug to search for
+ * @param locale Locale code
+ * @param categories Flat array of all categories
+ * @returns Category if found, undefined otherwise
+ */
+declare function findCategoryBySlug(slug: string, locale: string, categories: BlogCategory[]): BlogCategory | undefined;
+
+/**
+ * Utility for merging Tailwind CSS class names
+ * Combines clsx for conditional classes with tailwind-merge to handle conflicts
+ */
+
+/**
+ * Merge class names intelligently
+ * - Uses clsx for conditional classes
+ * - Uses tailwind-merge to deduplicate and resolve conflicts
+ *
+ * @example
+ * cn("px-2 py-1", condition && "bg-blue-500")
+ * cn({ "font-bold": isActive }, "text-lg")
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * CSS Resolution Utilities
+ * Converts CMS type system values (ColorReference, BorderConfig, ResponsiveValue)
+ * into CSS strings for rendering.
+ */
+
+/**
+ * Minify CSS by removing comments, extra whitespace, and unnecessary characters
+ */
+declare function minifyCSS(css: string): string;
+/**
+ * Resolve a ColorReference to a CSS color string
+ */
+declare function resolveColorToCSS(colorRef: ColorReference | undefined, target?: "background" | "foreground"): string | undefined;
+/**
+ * Resolve multiple ColorReferences to CSS color strings
+ */
+declare function resolveColorsToCSS<T extends Record<string, ColorReference | undefined>>(colorRefs: T): Partial<Record<keyof T, string>>;
+/**
+ * Resolve a BorderConfig to CSS border properties
+ */
+declare function resolveBorderToCSS(borderConfig: BorderConfig | undefined): Record<string, string> | undefined;
+interface ResponsiveSpacingConfig {
+    border?: ResponsiveValue<BorderConfig>;
+    margin?: ResponsiveValue<string>;
+    padding?: ResponsiveValue<string>;
+    gap?: ResponsiveValue<string>;
+    shadow?: ResponsiveValue<ShadowConfig>;
+}
+/**
+ * Generate responsive CSS for spacing (margin, padding, gap, border) with media queries
+ */
+declare function generateResponsiveSpacingCSS(className: string, config: ResponsiveSpacingConfig): string | null;
+/**
+ * Check if a ResponsiveSpacingConfig has any margin values set
+ */
+declare function hasAnyMargin(config: ResponsiveSpacingConfig): boolean;
+/**
+ * Map animation timing name to CSS timing function
+ */
+declare function getAnimationTimingFunction(timing?: string): string;
+
+/**
+ * Get localized string with proper fallback logic
+ * 1. Try user's preferred locale (from cookie or browser)
+ * 2. Try default locale (from deployment config)
+ * 3. Try 'en' as ultimate fallback
+ * 4. Return first available value as last resort
+ */
+declare function getLocalizedString(value: string | LocalizedString | null | undefined, options?: {
+    preferredLocale?: string | null;
+    defaultLocale?: string;
+    supportedLocales?: string[];
+}): string;
+/**
+ * Get all available locales from a localized string
+ */
+declare function getAvailableLocales(value: string | LocalizedString): string[];
+/**
+ * Check if a value is a localized string object
+ */
+declare function isLocalizedString(value: unknown): value is LocalizedString;
+/**
+ * Detect locale from various sources (URL, browser, config)
+ * Priority: URL param > path segment > browser language > default
+ * Note: This function requires browser environment
+ */
+declare function detectLocale(defaultLocale?: string, supportedLocales?: string[]): string;
+/**
+ * Format locale for HTML lang attribute (e.g., 'en-US')
+ */
+declare function formatLocaleForHtml(locale: string): string;
+
+/**
+ * Utility functions for working with responsive values
+ */
+
+/** A responsive value where every breakpoint -- including base -- is optional. */
+type NormalizedResponsiveValue<T> = {
+    base?: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+    "2xl"?: T;
+};
+/**
+ * Normalize an optional `ResponsiveValue<T>` into a flat object where every
+ * breakpoint key is optional. Useful for CSS generation loops.
+ *
+ * - `undefined`  -> `{}`
+ * - `"8px"`      -> `{ base: "8px" }`
+ * - `{ base: "8px", md: "16px" }` -> same
+ */
+declare function normalizeResponsiveValue<T>(value: ResponsiveValue<T> | undefined): NormalizedResponsiveValue<T>;
+/**
+ * Type guard to check if a value is a ResponsiveConfig
+ * Requires the object to have a "base" property
+ */
+declare function isResponsiveConfig<T>(value: ResponsiveValue<T>): value is ResponsiveConfig<T>;
+/**
+ * Get value for a specific breakpoint with fallback to base
+ */
+declare function getBreakpointValue<T>(value: ResponsiveValue<T>, breakpoint: BreakpointWithBase): T;
+/**
+ * Get all defined breakpoints in a responsive value
+ */
+declare function getDefinedBreakpoints<T>(value: ResponsiveValue<T>): BreakpointWithBase[];
+/**
+ * Convert a single value or responsive value to a ResponsiveConfig
+ */
+declare function toResponsiveConfig<T>(fields: {
+    base: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+    "2xl"?: T;
+}): ResponsiveConfig<T>;
+/**
+ * Convert a ResponsiveConfig to flat breakpoint fields
+ */
+declare function fromResponsiveConfig<T>(value: ResponsiveValue<T>): {
+    base: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+    "2xl"?: T;
+};
+
+/**
+ * Schedule Resolver
+ * Framework-agnostic content scheduling utilities
+ */
+/**
+ * Check if content is currently visible based on schedule metadata.
+ * Returns true if the content should be shown to visitors.
+ *
+ * @param publishAt - ISO 8601 timestamp when content should become visible
+ * @param expiresAt - ISO 8601 timestamp when content should stop being visible
+ * @param now - Optional current time (defaults to new Date())
+ * @returns true if content is visible, false otherwise
+ */
+declare function isContentVisible(publishAt: string | null | undefined, expiresAt: string | null | undefined, now?: Date): boolean;
+/**
+ * Filter a list of items based on schedule metadata.
+ * Each item must have optional publish_at and expires_at fields.
+ *
+ * @param items - Array of items with schedule metadata
+ * @param now - Optional current time (defaults to new Date())
+ * @returns Filtered array containing only currently visible items
+ */
+declare function filterScheduledContent<T extends {
+    publish_at?: string;
+    expires_at?: string;
+}>(items: T[], now?: Date): T[];
+
+/**
+ * Style Utilities
+ * Helpers to convert CMS config values to CSS strings and Tailwind classes.
+ * For CSS resolution utilities (resolveColorToCSS, resolveBorderToCSS, etc.)
+ * see css.utils.ts.
+ */
+
+/**
+ * Convert border config to CSS string
+ */
+declare function borderToStyle(border: ResponsiveValue<BorderConfig> | undefined): string;
+/**
+ * Format shadow config to CSS box-shadow value
+ */
+declare function formatShadow(shadow: ShadowConfig | undefined): string;
+/**
+ * Convert padding config to Tailwind class
+ */
+declare function paddingToClass(padding?: string): string;
+/**
+ * Convert padding top config to Tailwind class
+ */
+declare function paddingTopToClass(paddingTop?: string): string;
+/**
+ * Convert padding bottom config to Tailwind class
+ */
+declare function paddingBottomToClass(paddingBottom?: string): string;
+/**
+ * Convert spacing config to Tailwind class
+ */
+declare function spacingToClass(spacing?: string): string;
+/**
+ * Convert max-width config to Tailwind class
+ */
+declare function widthToClass(width?: string): string;
+/**
+ * Convert color config to inline style object
+ */
+declare function colorToStyle(color?: string): {
+    backgroundColor?: string;
+};
+/**
+ * Convert gap config to Tailwind class
+ */
+declare function gapToClass(gap?: number): string;
+
+/**
+ * Password Protection Resolution Utilities
+ *
+ * Framework-agnostic utilities for handling password-protected content.
+ * These utilities determine if content is password-protected and filter
+ * out protected content from lists (e.g., blog post listings).
+ *
+ * According to the architecture:
+ * - Backend returns ALL content with metadata
+ * - Engine/frontend decides visibility at render time
+ * - Password protection is checked on the client side
+ */
+/**
+ * Check if content is password-protected
+ * @param password_protected - Whether the content requires a password
+ * @returns True if content is password-protected, false otherwise
+ */
+declare function isPasswordProtected(password_protected?: boolean): boolean;
+/**
+ * Filter password-protected content from a list
+ * Useful for listings like blog posts where we don't want to show protected items
+ * @param items - Array of items with password_protected metadata
+ * @returns Filtered array with only non-protected items
+ */
+declare function filterPasswordProtectedContent<T extends {
+    password_protected?: boolean;
+}>(items: T[]): T[];
+
+/**
+ * JSON-LD structured data generation utilities.
+ *
+ * Produces a Schema.org @graph for pages, blog posts, and the overall site,
+ * using data already available in the CMS (website config, page/post metadata,
+ * organization config).
+ */
+
+interface JsonLdInput {
+    /** Canonical site origin, e.g. "https://example.com" */
+    siteUrl: string;
+    /** Current page path, e.g. "/about" */
+    path: string;
+    /** Current locale code */
+    locale: string;
+    /** Human-readable site name */
+    siteName: string;
+    /** Optional site description */
+    siteDescription?: string;
+    /** Organization config from WebsiteConfig */
+    organization?: OrganizationInfo;
+    /** Page-specific data (mutually exclusive with blogPost) */
+    page?: {
+        title: string;
+        description?: string;
+        schemaType?: string;
+        datePublished?: string;
+        dateModified?: string;
+        ogImage?: string;
+    };
+    /** Blog post data (mutually exclusive with page) */
+    blogPost?: {
+        title: string;
+        excerpt?: string;
+        datePublished: string;
+        dateModified?: string;
+        authorName?: string;
+        authorUrl?: string;
+        categories?: string[];
+        featuredImage?: string;
+    };
+    /** Explicit breadcrumb items; auto-built from path if omitted */
+    breadcrumbs?: {
+        name: string;
+        path: string;
+    }[];
+}
+/**
+ * Derive breadcrumb items from a URL path.
+ *
+ * "/" -> [{ name: "Home", path: "/" }]
+ * "/about" -> [{ name: "Home", path: "/" }, { name: "About", path: "/about" }]
+ * "/blog/my-post" -> [Home, Blog, My Post]
+ */
+declare function buildBreadcrumbs(path: string, pageTitle: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Generate a JSON-LD `@graph` object for the given page/post.
+ *
+ * When an override is provided externally (structured_data_override), callers
+ * should use the override directly instead of calling this function.
+ */
+declare function generateJsonLd(input: JsonLdInput): Record<string, unknown>;
+
+/**
+ * SEO utility functions for OTL CMS.
+ *
+ * These helpers extract common metadata from deployment configs and are used
+ * by both the engine's `generateMetadata` and component-level code.
+ *
+ * They are environment-agnostic: callers pass an explicit `siteUrlOverride`
+ * (e.g. from `process.env.NEXT_PUBLIC_SITE_URL`) instead of reading env vars
+ * directly, keeping the package framework-independent.
+ */
+/**
+ * Derive the public site origin (no trailing slash).
+ *
+ * Priority:
+ *  1. `siteUrlOverride` (e.g. env var)
+ *  2. First custom domain from deployment config
+ *  3. Subdomain-based OTL Studio URL
+ */
+declare function deriveSiteUrl(configs: Record<string, unknown>, siteUrlOverride?: string): string;
+/** Extract the localized site name from configs. */
+declare function deriveSiteName(configs: Record<string, unknown>, locale: string): string;
+/** Extract the localized site description from configs. */
+declare function deriveSiteDescription(configs: Record<string, unknown>, locale: string): string | undefined;
+/**
+ * Detect a locale prefix from the first URL segment.
+ *
+ * Returns `[locale, pathWithoutPrefix]`.  If the first segment is not a
+ * recognised locale, the deployment's default locale and the original path
+ * are returned unchanged.
+ */
+declare function detectLocaleFromSegments(segments: string[], fullPath: string, supportedLocales: string[], defaultLocale: string): [string, string];
+/**
+ * Convert a short locale code to the `og:locale` format.
+ *
+ * "en" -> "en_US", "de" -> "de_DE", etc.
+ * If the code is already in `xx_XX` form it is returned as-is.
+ */
+declare function localeToOgFormat(locale: string): string;
+/**
+ * Build hreflang alternate URLs for multi-locale support.
+ *
+ * Uses the locale-prefix pattern: the default locale maps to the bare path
+ * while other locales are prefixed (`/de/path`).  An `x-default` entry
+ * points to the un-prefixed URL.
+ *
+ * Returns `undefined` when there is only a single locale (hreflang would be
+ * pointless).
+ */
+declare function buildHreflangAlternates(siteUrl: string, path: string, supportedLocales: string[], defaultLocale: string): Record<string, string> | undefined;
+interface PaginationInfo {
+    page: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Walk through enriched layout sections/blocks and return the first
+ * pagination object found (from a `blog-post-list` or `blog-pagination`
+ * block's `data.pagination`).
+ */
+declare function extractPaginationFromLayout(layout: unknown[] | undefined): PaginationInfo | null;
+
+export { type CategoryTreeNode, type JsonLdInput, type MultivariateFormBlockData, type MultivariatePageContent, type NormalizedResponsiveValue, type PaginationInfo, type ResponsiveSpacingConfig, type VariantConfig, borderToStyle, buildBreadcrumbs, buildCategoryTree, buildHreflangAlternates, cn, colorToStyle, deriveSiteDescription, deriveSiteName, deriveSiteUrl, detectLocale, detectLocaleFromSegments, extractPaginationFromLayout, filterPasswordProtectedContent, filterScheduledContent, findCategoryBySlug, flattenCategoryTree, formatLocaleForHtml, formatShadow, fromResponsiveConfig, gapToClass, generateJsonLd, generateResponsiveSpacingCSS, getAnimationTimingFunction, getAvailableLocales, getBreakpointValue, getCategoryName, getCategoryPath, getCategorySlug, getDefinedBreakpoints, getDescendants, getLocalizedString, hasAnyMargin, isAncestor, isContentVisible, isLocalizedString, isMultivariateContent, isPasswordProtected, isResponsiveConfig, localeToOgFormat, minifyCSS, normalizeResponsiveValue, paddingBottomToClass, paddingToClass, paddingTopToClass, resolveBlogPostVariant, resolveBorderToCSS, resolveColorToCSS, resolveColorsToCSS, resolveFormVariantsInSections, resolvePageVariant, selectVariant, spacingToClass, toResponsiveConfig, widthToClass };