@otl-core/cms-utils 1.1.0 → 1.1.3

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { Category, ResponsiveValue, BorderConfig, ShadowConfig, ColorReference, LocalizedString, BreakpointWithBase, ResponsiveConfig, OrganizationInfo, VocabularyTerm } from '@otl-core/cms-types';
-import { ClassValue } from 'clsx';
+import { LocalizedString, ResponsiveValue, BreakpointWithBase, ResponsiveConfig, OrganizationInfo } from '@otl-core/cms-types';
 
 /**
  * A/B/n Variant Resolver
@@ -34,15 +33,6 @@ interface MultivariateFormBlockData {
         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.
  */
@@ -70,134 +60,6 @@ declare function resolveEntryVariant(content: Record<string, unknown>, bucket: n
  */
 declare function resolveFormVariantsInSections(sections: unknown[], bucket: number): unknown[];
 
-/**
- * Category utility functions
- */
-
-/**
- * Tree node with children
- */
-interface CategoryTreeNode extends Category {
-    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: Category[]): 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[]): Category[];
-/**
- * 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: Category[], locale?: string): Category[];
-/**
- * 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: Category, 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: Category, 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: Category[]): 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: Category[]): Category[];
-/**
- * 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: Category[]): Category | 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)
@@ -210,47 +72,11 @@ declare function getLocalizedString(value: string | LocalizedString | null | und
     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
@@ -260,32 +86,6 @@ declare function isResponsiveConfig<T>(value: ResponsiveValue<T>): value is Resp
  * 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
@@ -301,64 +101,6 @@ declare function fromResponsiveConfig<T>(value: ResponsiveValue<T>): {
  * @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
@@ -378,15 +120,6 @@ declare function gapToClass(gap?: number): string;
  * @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.
@@ -458,35 +191,7 @@ declare function generateJsonLd(input: JsonLdInput): Record<string, unknown>;
 
 /**
  * SEO utility functions for OTL CMS.
- *
- * These helpers extract common metadata from site 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 site 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 site'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.
  *
@@ -518,19 +223,4 @@ interface PaginationInfo {
  */
 declare function extractPaginationFromLayout(layout: unknown[] | undefined): PaginationInfo | null;
 
-/**
- * Resolve a vocabulary term to a plain string.
- * Fallback chain: exact locale -> defaultLocale -> first available key -> "".
- */
-declare function resolveVocabularyTerm(term: VocabularyTerm, locale: string, defaultLocale?: string): string;
-/**
- * Return a URL-safe slug of the resolved vocabulary term.
- */
-declare function vocabularySlug(term: VocabularyTerm, locale: string, defaultLocale?: string): string;
-/**
- * Return the set of locales that are missing a translation for this term.
- * Only relevant for localized (object) terms; returns empty array for plain strings.
- */
-declare function missingVocabularyLocales(term: VocabularyTerm, requiredLocales: string[]): string[];
-
-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, missingVocabularyLocales, normalizeResponsiveValue, paddingBottomToClass, paddingToClass, paddingTopToClass, resolveBorderToCSS, resolveColorToCSS, resolveColorsToCSS, resolveEntryVariant, resolveFormVariantsInSections, resolvePageVariant, resolveVocabularyTerm, selectVariant, spacingToClass, toResponsiveConfig, vocabularySlug, widthToClass };
+export { type JsonLdInput, type MultivariateFormBlockData, type MultivariatePageContent, type PaginationInfo, type VariantConfig, buildBreadcrumbs, buildHreflangAlternates, extractPaginationFromLayout, generateJsonLd, getBreakpointValue, getLocalizedString, isContentVisible, isMultivariateContent, isPasswordProtected, isResponsiveConfig, localeToOgFormat, resolveEntryVariant, resolveFormVariantsInSections, resolvePageVariant };