osi-cards-lib 1.2.0 → 1.2.1

package/index.d.ts

@@ -1,6 +1,7 @@
 import * as i0 from '@angular/core';
-import { OnDestroy, OnChanges, EventEmitter, ChangeDetectorRef, SimpleChanges, AfterViewInit, ElementRef, QueryList, OnInit } from '@angular/core';
+import { OnDestroy, OnChanges, EventEmitter, ChangeDetectorRef, SimpleChanges, Type, Provider, EnvironmentProviders, AfterViewInit, ElementRef, QueryList, OnInit } from '@angular/core';
 import * as rxjs from 'rxjs';
+import { Observable } from 'rxjs';
 import * as i1 from 'lucide-angular';
 
 type CardType = 'company' | 'contact' | 'opportunity' | 'product' | 'analytics' | 'event' | 'project' | 'sko';
@@ -356,10 +357,34 @@ declare class MagneticTiltService implements OnDestroy {
     private rafId;
     private pendingUpdate;
     private lastCalculations;
+    private currentRotateY;
+    private currentRotateX;
+    private currentGlowBlur;
+    private currentGlowOpacity;
+    private currentReflectionOpacity;
+    private targetRotateY;
+    private targetRotateX;
+    private targetGlowBlur;
+    private targetGlowOpacity;
+    private targetReflectionOpacity;
+    private smoothingRafId;
     private readonly CACHE_DURATION;
     private readonly ngZone;
     calculateTilt(mousePosition: MousePosition, element: HTMLElement | null): void;
     private processTiltUpdate;
+    /**
+     * Linear interpolation (lerp) for smooth value transitions
+     * @param start Current value
+     * @param end Target value
+     * @param factor Interpolation factor (0-1)
+     */
+    private lerp;
+    /**
+     * Continue smoothing animation until values are close to target
+     * Uses the latest target values stored in the service
+     * Optimized for smooth cursor following
+     */
+    private continueSmoothing;
     private getElementCache;
     private hasCalculationsChanged;
     private resetTimeoutId;
@@ -417,67 +442,6 @@ declare class SectionUtilsService {
     static ɵprov: i0.ɵɵInjectableDeclaration<SectionUtilsService>;
 }
 
-type CardChangeType = 'content' | 'structural';
-interface CardDiffResult {
-    card: AICardConfig;
-    changeType: CardChangeType;
-}
-/**
- * Deep comparison utility for card objects
- * Uses content hashing instead of JSON.stringify for better performance
- */
-declare class CardDiffUtil {
-    /**
-     * Creates an updated card with only changed sections/fields updated
-     * Preserves references to unchanged sections for optimal performance
-     */
-    static mergeCardUpdates(oldCard: AICardConfig, newCard: AICardConfig): CardDiffResult;
-    private static didStructureChange;
-    /**
-     * Merges sections array, preserving references to unchanged sections
-     */
-    private static mergeSections;
-    /**
-     * Merges a single section, preserving references to unchanged fields/items
-     */
-    private static mergeSection;
-    /**
-     * Merges fields array, preserving references to unchanged fields
-     * Uses content hashing instead of JSON.stringify for better performance
-     */
-    private static mergeFields;
-    /**
-     * Merges items array, preserving references to unchanged items
-     * Uses content hashing instead of JSON.stringify for better performance
-     */
-    private static mergeItems;
-    /**
-     * Fast equality check for cards
-     */
-    private static areCardsEqual;
-    /**
-     * Fast equality check for sections arrays
-     */
-    private static areSectionsEqual;
-    /**
-     * Fast equality check for fields arrays
-     */
-    private static areFieldsEqual;
-    /**
-     * Fast equality check for items arrays
-     */
-    private static areItemsEqual;
-}
-
-type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
-declare function getBreakpointFromWidth(width: number): Breakpoint;
-
-declare class LucideIconsModule {
-    static ɵfac: i0.ɵɵFactoryDeclaration<LucideIconsModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<LucideIconsModule, never, [typeof i1.LucideAngularModule], [typeof i1.LucideAngularModule]>;
-    static ɵinj: i0.ɵɵInjectorDeclaration<LucideIconsModule>;
-}
-
 /**
  * Base interface for section field/item interactions
  */
@@ -614,6 +578,185 @@ declare abstract class BaseSectionComponent<T extends CardField | CardItem = Car
     static ɵcmp: i0.ɵɵComponentDeclaration<BaseSectionComponent<any>, "ng-component", never, { "section": { "alias": "section"; "required": true; }; }, { "fieldInteraction": "fieldInteraction"; "itemInteraction": "itemInteraction"; }, never, never, true, never>;
 }
 
+/**
+ * Plugin metadata for a custom section type
+ */
+interface SectionPluginMetadata {
+    /** Unique identifier for the section type */
+    type: string;
+    /** Display name for the section type */
+    name: string;
+    /** Description of what this section type does */
+    description?: string;
+    /** Version of the plugin */
+    version?: string;
+    /** Author information */
+    author?: string;
+}
+/**
+ * Configuration options for a section plugin
+ */
+interface SectionPluginConfig {
+    /** Priority for plugin resolution (higher = higher priority) */
+    priority?: number;
+    /** Whether this plugin should override built-in sections with the same type */
+    override?: boolean;
+    /** Additional metadata */
+    metadata?: Partial<SectionPluginMetadata>;
+}
+/**
+ * Plugin interface that custom section components must implement
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-custom-section',
+ *   standalone: true,
+ *   template: `...`
+ * })
+ * export class CustomSectionComponent extends BaseSectionComponent implements SectionPlugin {
+ *   static readonly PLUGIN_TYPE = 'custom-section';
+ *
+ *   getPluginType(): string {
+ *     return CustomSectionComponent.PLUGIN_TYPE;
+ *   }
+ *
+ *   canHandle(section: CardSection): boolean {
+ *     return section.type === 'custom-section';
+ *   }
+ * }
+ * ```
+ */
+interface SectionPlugin {
+    /**
+     * Returns the section type this plugin handles
+     */
+    getPluginType(): string;
+    /**
+     * Determines if this plugin can handle the given section
+     * @param section - The section to check
+     * @returns True if this plugin can handle the section
+     */
+    canHandle(section: CardSection): boolean;
+}
+/**
+ * Extended plugin interface with component type
+ */
+interface RegisteredSectionPlugin extends SectionPluginMetadata {
+    /** The component class that handles this section type */
+    component: Type<BaseSectionComponent>;
+    /** Configuration options */
+    config: SectionPluginConfig;
+    /** Priority for resolution (default: 0) */
+    priority: number;
+}
+
+/**
+ * Registry service for managing custom section type plugins
+ *
+ * Allows external developers to register custom section components that extend
+ * the library's built-in section types.
+ *
+ * @example
+ * ```typescript
+ * const registry = inject(SectionPluginRegistry);
+ *
+ * // Register a custom section plugin
+ * registry.register({
+ *   type: 'custom-section',
+ *   name: 'Custom Section',
+ *   description: 'A custom section type',
+ *   component: CustomSectionComponent,
+ *   config: {
+ *     priority: 10,
+ *     override: false
+ *   }
+ * });
+ *
+ * // Get a component for a section type
+ * const component = registry.getComponent(section);
+ * ```
+ */
+declare class SectionPluginRegistry {
+    private plugins;
+    private readonly defaultFallback;
+    /**
+     * Register a custom section plugin
+     *
+     * @param plugin - The plugin metadata and component
+     * @throws Error if plugin type already exists and override is false
+     */
+    register(plugin: {
+        type: string;
+        name: string;
+        description?: string;
+        component: Type<BaseSectionComponent & SectionPlugin>;
+        config?: SectionPluginConfig;
+        metadata?: Partial<SectionPluginMetadata>;
+    }): void;
+    /**
+     * Unregister a plugin
+     *
+     * @param type - The section type to unregister
+     * @returns True if plugin was removed, false if not found
+     */
+    unregister(type: string): boolean;
+    /**
+     * Get the component class for a given section type
+     *
+     * @param sectionType - The section type identifier
+     * @returns The component class or null if not found
+     */
+    getComponent(sectionType: string): Type<BaseSectionComponent> | null;
+    /**
+     * Get the component class for a section
+     * Returns null if no plugin is registered (built-in sections will handle it)
+     *
+     * @param section - The card section
+     * @returns The component class or null if no plugin registered
+     */
+    getComponentForSection(section: CardSection): Type<BaseSectionComponent> | null;
+    /**
+     * Check if a plugin is registered for a section type
+     *
+     * @param type - The section type identifier
+     * @returns True if a plugin is registered
+     */
+    hasPlugin(type: string): boolean;
+    /**
+     * Get all registered plugins
+     *
+     * @returns Array of registered plugin metadata
+     */
+    getPlugins(): RegisteredSectionPlugin[];
+    /**
+     * Get plugin metadata for a specific type
+     *
+     * @param type - The section type identifier
+     * @returns Plugin metadata or null if not found
+     */
+    getPluginMetadata(type: string): RegisteredSectionPlugin | null;
+    /**
+     * Clear all registered plugins
+     */
+    clear(): void;
+    /**
+     * Register multiple plugins at once
+     *
+     * @param plugins - Array of plugins to register
+     */
+    registerAll(plugins: Array<{
+        type: string;
+        name: string;
+        description?: string;
+        component: Type<BaseSectionComponent & SectionPlugin>;
+        config?: SectionPluginConfig;
+        metadata?: Partial<SectionPluginMetadata>;
+    }>): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SectionPluginRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SectionPluginRegistry>;
+}
+
 type InfoField = CardField & {
     description?: string;
     change?: number;
@@ -654,17 +797,887 @@ interface SectionRenderEvent {
 declare class SectionRendererComponent {
     section: CardSection;
     sectionEvent: EventEmitter<SectionRenderEvent>;
+    private readonly pluginRegistry;
     get sectionTypeAttribute(): string;
     get sectionIdAttribute(): string | null;
+    /**
+     * Get the component type for the current section, checking plugins first
+     */
+    get sectionComponent(): Type<BaseSectionComponent> | null;
+    /**
+     * Check if current section uses a plugin
+     */
+    get usesPlugin(): boolean;
     get resolvedType(): string;
     onInfoFieldInteraction(event: InfoSectionFieldInteraction): void;
     emitFieldInteraction(field: CardField, metadata?: Record<string, unknown>): void;
     emitItemInteraction(item: CardItem | CardField, metadata?: Record<string, unknown>): void;
     emitActionInteraction(action: CardAction, metadata?: Record<string, unknown>): void;
+    /**
+     * Handle events from plugin components
+     */
+    onPluginSectionEvent(event: SectionRenderEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SectionRendererComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SectionRendererComponent, "app-section-renderer", never, { "section": { "alias": "section"; "required": true; }; }, { "sectionEvent": "sectionEvent"; }, never, never, true, never>;
 }
 
+/**
+ * Event middleware interface for intercepting and transforming card events
+ *
+ * Middleware functions can be used to:
+ * - Log events for debugging
+ * - Transform event data
+ * - Add analytics tracking
+ * - Implement custom event filtering
+ * - Enrich events with additional metadata
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: EventMiddleware = {
+ *   handle: (event, next) => {
+ *     console.log('Event:', event);
+ *     return next(event);
+ *   }
+ * };
+ * ```
+ */
+interface EventMiddleware {
+    /**
+     * Handle an event, optionally transforming it before passing to next middleware
+     *
+     * @param event - The event to handle
+     * @param next - Function to call the next middleware in the chain
+     * @returns The processed event (can be the original or transformed)
+     */
+    handle(event: SectionRenderEvent, next: (event: SectionRenderEvent) => SectionRenderEvent): SectionRenderEvent;
+    /**
+     * Optional priority for middleware ordering (higher = earlier in chain)
+     */
+    priority?: number;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler = (event: SectionRenderEvent) => void | SectionRenderEvent;
+/**
+ * Event transformation function type
+ */
+type EventTransformer = (event: SectionRenderEvent) => SectionRenderEvent;
+/**
+ * Event filter function type
+ */
+type EventFilter = (event: SectionRenderEvent) => boolean;
+
+/**
+ * Event Middleware Service
+ *
+ * Manages event middleware chains for processing card events before they reach handlers.
+ * Supports logging, transformation, filtering, and analytics integration.
+ *
+ * @example
+ * ```typescript
+ * const eventService = inject(EventMiddlewareService);
+ *
+ * // Add logging middleware
+ * eventService.addMiddleware({
+ *   handle: (event, next) => {
+ *     console.log('Event:', event);
+ *     return next(event);
+ *   }
+ * });
+ *
+ * // Subscribe to processed events
+ * eventService.processedEvents$.subscribe(event => {
+ *   // Handle event
+ * });
+ * ```
+ */
+declare class EventMiddlewareService {
+    private middleware;
+    private processedEventsSubject;
+    private rawEventsSubject;
+    /** Observable of processed events (after middleware chain) */
+    processedEvents$: Observable<SectionRenderEvent>;
+    /** Observable of raw events (before middleware) */
+    rawEvents$: Observable<SectionRenderEvent>;
+    /**
+     * Add middleware to the chain
+     *
+     * @param middleware - Middleware to add
+     * @returns Function to remove the middleware
+     */
+    addMiddleware(middleware: EventMiddleware): () => void;
+    /**
+     * Remove middleware from the chain
+     *
+     * @param middleware - Middleware to remove
+     */
+    removeMiddleware(middleware: EventMiddleware): void;
+    /**
+     * Clear all middleware
+     */
+    clearMiddleware(): void;
+    /**
+     * Process an event through the middleware chain
+     *
+     * @param event - Event to process
+     * @returns Processed event
+     */
+    processEvent(event: SectionRenderEvent): SectionRenderEvent;
+    /**
+     * Create a logging middleware
+     *
+     * @param logger - Optional logger function (defaults to console.log)
+     * @returns Logging middleware
+     */
+    createLoggingMiddleware(logger?: (message: string, event: SectionRenderEvent) => void): EventMiddleware;
+    /**
+     * Create a filtering middleware
+     *
+     * @param filter - Filter function
+     * @returns Filtering middleware
+     */
+    createFilterMiddleware(filter: EventFilter): EventMiddleware;
+    /**
+     * Create a transformation middleware
+     *
+     * @param transformer - Transformation function
+     * @returns Transformation middleware
+     */
+    createTransformMiddleware(transformer: EventTransformer): EventMiddleware;
+    /**
+     * Create an analytics middleware
+     *
+     * @param trackEvent - Analytics tracking function
+     * @returns Analytics middleware
+     */
+    createAnalyticsMiddleware(trackEvent: (eventName: string, properties: Record<string, unknown>) => void): EventMiddleware;
+    /**
+     * Sort middleware by priority (higher priority first)
+     */
+    private sortMiddleware;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EventMiddlewareService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EventMiddlewareService>;
+}
+
+type CardChangeType = 'content' | 'structural';
+interface CardDiffResult {
+    card: AICardConfig;
+    changeType: CardChangeType;
+}
+/**
+ * Deep comparison utility for card objects
+ * Uses content hashing instead of JSON.stringify for better performance
+ */
+declare class CardDiffUtil {
+    /**
+     * Creates an updated card with only changed sections/fields updated
+     * Preserves references to unchanged sections for optimal performance
+     */
+    static mergeCardUpdates(oldCard: AICardConfig, newCard: AICardConfig): CardDiffResult;
+    private static didStructureChange;
+    /**
+     * Merges sections array, preserving references to unchanged sections
+     */
+    private static mergeSections;
+    /**
+     * Merges a single section, preserving references to unchanged fields/items
+     */
+    private static mergeSection;
+    /**
+     * Merges fields array, preserving references to unchanged fields
+     * Uses content hashing instead of JSON.stringify for better performance
+     */
+    private static mergeFields;
+    /**
+     * Merges items array, preserving references to unchanged items
+     * Uses content hashing instead of JSON.stringify for better performance
+     */
+    private static mergeItems;
+    /**
+     * Fast equality check for cards
+     */
+    private static areCardsEqual;
+    /**
+     * Fast equality check for sections arrays
+     */
+    private static areSectionsEqual;
+    /**
+     * Fast equality check for fields arrays
+     */
+    private static areFieldsEqual;
+    /**
+     * Fast equality check for items arrays
+     */
+    private static areItemsEqual;
+}
+
+type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+declare function getBreakpointFromWidth(width: number): Breakpoint;
+
+/**
+ * Card Spawner Utilities
+ *
+ * Helper functions for dynamically instantiating and managing card components,
+ * particularly useful for agentic flows and LLM integrations.
+ */
+/**
+ * Creates an empty card configuration for initialization
+ */
+declare function createEmptyCard(title?: string): AICardConfig;
+/**
+ * Creates a skeleton card configuration for loading states
+ */
+declare function createSkeletonCard(): AICardConfig;
+/**
+ * Merges a partial card configuration into an existing card configuration
+ * This is useful for progressive updates during streaming
+ */
+declare function mergeCardConfig(existing: AICardConfig, update: Partial<AICardConfig>): AICardConfig;
+/**
+ * Merges sections arrays, updating existing sections or adding new ones
+ */
+declare function mergeSections(existing: CardSection[], updates: CardSection[]): CardSection[];
+/**
+ * Validates a card configuration for completeness
+ */
+declare function validateCardConfig(card: Partial<AICardConfig>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Creates a card configuration from a partial update
+ * Useful when receiving streaming updates that may be incomplete
+ */
+declare function createCardFromPartial(partial: Partial<AICardConfig>, defaults?: Partial<AICardConfig>): AICardConfig;
+/**
+ * Checks if a card configuration is complete (all required fields present)
+ */
+declare function isCardComplete(card: Partial<AICardConfig>): boolean;
+/**
+ * Creates a card configuration with error information
+ */
+declare function createErrorCard(error: Error | string, title?: string): AICardConfig;
+/**
+ * Prepares a card configuration for streaming updates
+ * Ensures the card has the necessary structure for progressive updates
+ */
+declare function prepareCardForStreaming(card: Partial<AICardConfig>): AICardConfig;
+/**
+ * Updates a card configuration incrementally
+ * Optimized for streaming scenarios where partial updates arrive
+ */
+declare function updateCardIncremental(existing: AICardConfig, update: Partial<AICardConfig>): AICardConfig;
+/**
+ * Creates a copy of a card configuration (deep clone)
+ */
+declare function cloneCardConfig(card: AICardConfig): AICardConfig;
+
+/**
+ * Style Validator Utilities
+ *
+ * Helper functions to validate that the OSI Cards design system styles
+ * are properly loaded and configured.
+ */
+/**
+ * Result of style validation
+ */
+interface StyleValidationResult {
+    valid: boolean;
+    missing: string[];
+    recommended: string[];
+    warnings: string[];
+}
+/**
+ * Validates that required CSS variables are present
+ *
+ * @param element - Optional element to check (defaults to document root)
+ * @returns Validation result with missing variables and warnings
+ *
+ * @example
+ * ```typescript
+ * const validation = validateStyles();
+ * if (!validation.valid) {
+ *   console.warn('Missing styles:', validation.missing);
+ * }
+ * ```
+ */
+declare function validateStyles(element?: HTMLElement): StyleValidationResult;
+/**
+ * Validates styles and logs warnings to console if issues are found
+ *
+ * @param element - Optional element to check
+ * @param logToConsole - Whether to log warnings to console (default: true)
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // In component ngOnInit or after styles load
+ * validateAndWarnStyles();
+ * ```
+ */
+declare function validateAndWarnStyles(element?: HTMLElement, logToConsole?: boolean): StyleValidationResult;
+/**
+ * Checks if a specific CSS variable is defined
+ *
+ * @param variableName - Name of the CSS variable (with or without -- prefix)
+ * @param element - Optional element to check
+ * @returns True if the variable is defined and has a value
+ */
+declare function isCSSVariableDefined(variableName: string, element?: HTMLElement): boolean;
+/**
+ * Gets the value of a CSS variable
+ *
+ * @param variableName - Name of the CSS variable (with or without -- prefix)
+ * @param element - Optional element to check
+ * @returns The CSS variable value, or null if not defined
+ */
+declare function getCSSVariableValue(variableName: string, element?: HTMLElement): string | null;
+/**
+ * Checks if styles are loaded by looking for a specific marker class or variable
+ * This is a lighter check than full validation
+ *
+ * @returns True if styles appear to be loaded
+ */
+declare function areStylesLoaded(): boolean;
+/**
+ * Waits for styles to be loaded by polling
+ * Useful when styles are loaded asynchronously
+ *
+ * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+ * @param pollInterval - How often to check in milliseconds (default: 100)
+ * @returns Promise that resolves when styles are loaded or timeout is reached
+ */
+declare function waitForStyles(timeout?: number, pollInterval?: number): Promise<boolean>;
+
+declare class LucideIconsModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<LucideIconsModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<LucideIconsModule, never, [typeof i1.LucideAngularModule], [typeof i1.LucideAngularModule]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<LucideIconsModule>;
+}
+
+/**
+ * Configuration options for OSI Cards Library
+ */
+interface OSICardsLibConfig {
+    /**
+     * Whether to enable animations. Defaults to true.
+     * Set to false to use noop animations (useful for testing or when animations are not desired).
+     */
+    enableAnimations?: boolean;
+}
+/**
+ * Provide OSI Cards Library with required providers
+ *
+ * This function provides all necessary providers for the OSI Cards library to function
+ * correctly in an Angular application. It includes:
+ * - Animation providers (required for component animations)
+ * - Service providers (services use providedIn: 'root' so they're automatically available)
+ *
+ * @param config - Optional configuration object
+ * @returns Array of providers to be added to your ApplicationConfig
+ *
+ * @example
+ * ```typescript
+ * // In your app.config.ts
+ * import { ApplicationConfig } from '@angular/core';
+ * import { provideOSICards } from 'osi-cards-lib';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideOSICards(), // Enable animations (default)
+ *     // ... other providers
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable animations (for testing or performance)
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideOSICards({ enableAnimations: false }),
+ *     // ... other providers
+ *   ]
+ * };
+ * ```
+ *
+ * @remarks
+ * - **REQUIRED**: You must call this function in your app.config.ts providers array
+ * - Animations are required for proper component behavior (entrance animations, transitions)
+ * - Services (MagneticTiltService, IconService, etc.) are automatically provided via providedIn: 'root'
+ * - Styles must be imported separately: @import 'osi-cards-lib/styles/_styles';
+ */
+declare function provideOSICards(config?: OSICardsLibConfig): (Provider | EnvironmentProviders)[];
+
+/**
+ * Theme configuration interface
+ */
+interface OSICardsThemeConfig {
+    /** Theme name (e.g., 'light', 'dark', 'high-contrast', 'custom') */
+    name: string;
+    /** CSS variable overrides */
+    variables: Record<string, string>;
+    /** Whether this theme is a built-in preset */
+    preset?: boolean;
+}
+/**
+ * Built-in theme presets
+ */
+type ThemePreset = 'light' | 'dark' | 'night' | 'day' | 'high-contrast' | 'custom';
+/**
+ * Theme Service
+ *
+ * Manages theme configuration and runtime theme switching for OSI Cards library.
+ * Supports built-in presets and custom themes via CSS custom properties.
+ *
+ * @example
+ * ```typescript
+ * const themeService = inject(ThemeService);
+ *
+ * // Switch to dark theme
+ * themeService.setTheme('night');
+ *
+ * // Apply custom theme
+ * themeService.applyCustomTheme({
+ *   name: 'my-brand',
+ *   variables: {
+ *     '--color-brand': '#ff0000',
+ *     '--card-padding': '20px'
+ *   }
+ * });
+ * ```
+ */
+declare class ThemeService {
+    private readonly platformId;
+    private readonly document;
+    private currentThemeSubject;
+    currentTheme$: Observable<ThemePreset | string>;
+    private customThemes;
+    private readonly rootElement;
+    constructor();
+    /**
+     * Get the current active theme
+     */
+    getCurrentTheme(): ThemePreset | string;
+    /**
+     * Set theme to a built-in preset
+     *
+     * @param preset - Built-in theme preset name
+     */
+    setTheme(preset: ThemePreset): void;
+    /**
+     * Apply a custom theme configuration
+     *
+     * @param config - Custom theme configuration
+     */
+    applyCustomTheme(config: OSICardsThemeConfig): void;
+    /**
+     * Apply CSS variables to the document root
+     *
+     * @param variables - Object mapping CSS variable names to values
+     */
+    applyCSSVariables(variables: Record<string, string>): void;
+    /**
+     * Reset CSS variables (useful when switching themes)
+     */
+    resetCSSVariables(): void;
+    /**
+     * Get a custom theme configuration
+     *
+     * @param name - Theme name
+     * @returns Theme configuration or null if not found
+     */
+    getCustomTheme(name: string): OSICardsThemeConfig | null;
+    /**
+     * Register a custom theme (without applying it)
+     *
+     * @param config - Custom theme configuration
+     */
+    registerTheme(config: OSICardsThemeConfig): void;
+    /**
+     * Remove a custom theme
+     *
+     * @param name - Theme name to remove
+     * @returns True if theme was removed, false if not found
+     */
+    unregisterTheme(name: string): boolean;
+    /**
+     * Get all registered custom themes
+     *
+     * @returns Array of custom theme configurations
+     */
+    getCustomThemes(): OSICardsThemeConfig[];
+    /**
+     * Validate a theme configuration
+     *
+     * @param config - Theme configuration to validate
+     * @returns Validation result with errors if any
+     */
+    validateTheme(config: OSICardsThemeConfig): {
+        valid: boolean;
+        errors: string[];
+    };
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeService>;
+}
+
+/**
+ * Light theme preset configuration
+ * Based on the day theme from the design system
+ */
+declare const lightTheme: OSICardsThemeConfig;
+
+/**
+ * Dark theme preset configuration
+ * Based on the night theme from the design system
+ */
+declare const darkTheme: OSICardsThemeConfig;
+
+/**
+ * High contrast theme preset for accessibility
+ * Provides maximum contrast for better visibility
+ */
+declare const highContrastTheme: OSICardsThemeConfig;
+
+/**
+ * Theme Builder Utility
+ *
+ * Helper functions for building and modifying theme configurations
+ */
+/**
+ * Create a theme configuration from a base theme with overrides
+ *
+ * @param baseTheme - Base theme configuration
+ * @param overrides - Variable overrides to apply
+ * @returns New theme configuration with overrides applied
+ *
+ * @example
+ * ```typescript
+ * const customTheme = buildThemeFromBase(lightTheme, {
+ *   '--color-brand': '#ff0000',
+ *   '--card-padding': '24px'
+ * });
+ * ```
+ */
+declare function buildThemeFromBase(baseTheme: OSICardsThemeConfig, overrides: Record<string, string>): OSICardsThemeConfig;
+/**
+ * Merge multiple theme configurations
+ * Later themes override earlier ones
+ *
+ * @param themes - Array of theme configurations to merge
+ * @returns Merged theme configuration
+ */
+declare function mergeThemes(...themes: OSICardsThemeConfig[]): OSICardsThemeConfig;
+/**
+ * Create a theme with only specific CSS variables
+ * Useful for partial theme customization
+ *
+ * @param name - Theme name
+ * @param variables - CSS variables to include
+ * @returns Theme configuration with only specified variables
+ */
+declare function createPartialTheme(name: string, variables: Record<string, string>): OSICardsThemeConfig;
+/**
+ * Validate CSS variable names
+ *
+ * @param variables - Object with CSS variable names as keys
+ * @returns Array of invalid variable names
+ */
+declare function validateCSSVariableNames(variables: Record<string, string>): string[];
+/**
+ * Generate a theme from a color palette
+ * Automatically generates related CSS variables from base colors
+ *
+ * @param name - Theme name
+ * @param colors - Color palette object
+ * @returns Theme configuration with generated variables
+ *
+ * @example
+ * ```typescript
+ * const theme = generateThemeFromPalette('my-brand', {
+ *   primary: '#ff7900',
+ *   background: '#ffffff',
+ *   foreground: '#000000'
+ * });
+ * ```
+ */
+declare function generateThemeFromPalette(name: string, colors: {
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    border?: string;
+}): OSICardsThemeConfig;
+
+/**
+ * Company Card Preset
+ *
+ * Factory functions for creating company profile cards with common sections.
+ */
+/**
+ * Options for company card preset
+ */
+interface CompanyCardOptions {
+    /** Company name */
+    name: string;
+    /** Company subtitle/description */
+    subtitle?: string;
+    /** Industry */
+    industry?: string;
+    /** Founded year */
+    founded?: string;
+    /** Number of employees */
+    employees?: string;
+    /** Headquarters location */
+    headquarters?: string;
+    /** Annual revenue */
+    revenue?: string;
+    /** Growth rate percentage */
+    growthRate?: number;
+    /** Market share percentage */
+    marketShare?: number;
+    /** Website URL */
+    websiteUrl?: string;
+    /** Additional custom sections */
+    customSections?: CardSection[];
+    /** Custom actions */
+    customActions?: CardAction[];
+}
+/**
+ * Create a basic company card
+ *
+ * @param options - Company card options
+ * @returns AICardConfig for a company card
+ *
+ * @example
+ * ```typescript
+ * const card = createCompanyCard({
+ *   name: 'Acme Corp',
+ *   industry: 'Technology',
+ *   employees: '500+',
+ *   websiteUrl: 'https://acme.com'
+ * });
+ * ```
+ */
+declare function createCompanyCard(options: CompanyCardOptions): AICardConfig;
+/**
+ * Create an enhanced company card with more sections
+ */
+declare function createEnhancedCompanyCard(options: CompanyCardOptions & {
+    financials?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    products?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}): AICardConfig;
+
+/**
+ * Contact Card Preset
+ *
+ * Factory functions for creating contact profile cards.
+ */
+/**
+ * Options for contact card preset
+ */
+interface ContactCardOptions {
+    /** Contact name */
+    name: string;
+    /** Job title */
+    jobTitle?: string;
+    /** Company name */
+    company?: string;
+    /** Location */
+    location?: string;
+    /** Years of experience */
+    experience?: string;
+    /** Email address */
+    email?: string;
+    /** Phone number */
+    phone?: string;
+    /** LinkedIn URL */
+    linkedIn?: string;
+    /** Performance metrics */
+    metrics?: Array<{
+        label: string;
+        value: string | number;
+        percentage?: number;
+        trend?: 'up' | 'down' | 'stable';
+    }>;
+    /** Custom sections */
+    customSections?: CardSection[];
+    /** Custom actions */
+    customActions?: CardAction[];
+}
+/**
+ * Create a basic contact card
+ *
+ * @param options - Contact card options
+ * @returns AICardConfig for a contact card
+ *
+ * @example
+ * ```typescript
+ * const card = createContactCard({
+ *   name: 'John Doe',
+ *   jobTitle: 'Sales Director',
+ *   email: 'john@example.com',
+ *   phone: '+1 555 1234'
+ * });
+ * ```
+ */
+declare function createContactCard(options: ContactCardOptions): AICardConfig;
+
+/**
+ * Analytics Dashboard Preset
+ *
+ * Factory functions for creating analytics dashboard cards.
+ */
+/**
+ * Options for analytics dashboard preset
+ */
+interface AnalyticsDashboardOptions {
+    /** Dashboard title */
+    title: string;
+    /** Dashboard subtitle */
+    subtitle?: string;
+    /** Dashboard type */
+    dashboardType?: string;
+    /** Data source */
+    dataSource?: string;
+    /** Update frequency */
+    updateFrequency?: string;
+    /** Time range */
+    timeRange?: string;
+    /** Key performance indicators */
+    kpis?: Array<{
+        label: string;
+        value: string | number;
+        percentage?: number;
+        performance?: 'excellent' | 'good' | 'fair' | 'poor';
+        trend?: 'up' | 'down' | 'stable' | 'neutral';
+    }>;
+    /** Chart data (optional) */
+    chartData?: {
+        labels: string[];
+        datasets: Array<{
+            label: string;
+            data: number[];
+        }>;
+    };
+    /** Dashboard URL */
+    dashboardUrl?: string;
+    /** Custom sections */
+    customSections?: CardSection[];
+    /** Custom actions */
+    customActions?: CardAction[];
+}
+/**
+ * Create an analytics dashboard card
+ *
+ * @param options - Analytics dashboard options
+ * @returns AICardConfig for an analytics dashboard
+ *
+ * @example
+ * ```typescript
+ * const card = createAnalyticsDashboard({
+ *   title: 'Sales Performance',
+ *   kpis: [
+ *     { label: 'Revenue', value: '$1.2M', percentage: 105, trend: 'up' },
+ *     { label: 'Conversion Rate', value: '32%', percentage: 32, trend: 'up' }
+ *   ]
+ * });
+ * ```
+ */
+declare function createAnalyticsDashboard(options: AnalyticsDashboardOptions): AICardConfig;
+
+/**
+ * Preset Factory
+ *
+ * Centralized factory for creating card presets with common configurations.
+ *
+ * @example
+ * ```typescript
+ * import { PresetFactory } from 'osi-cards-lib';
+ *
+ * // Create a company card
+ * const companyCard = PresetFactory.createCompany({
+ *   name: 'Acme Corp',
+ *   industry: 'Technology'
+ * });
+ *
+ * // Create a contact card
+ * const contactCard = PresetFactory.createContact({
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * ```
+ */
+declare class PresetFactory {
+    /**
+     * Create a company card
+     *
+     * @param options - Company card options
+     * @returns Company card configuration
+     */
+    static createCompany(options: CompanyCardOptions): AICardConfig;
+    /**
+     * Create an enhanced company card with additional sections
+     *
+     * @param options - Enhanced company card options
+     * @returns Enhanced company card configuration
+     */
+    static createEnhancedCompany(options: CompanyCardOptions & {
+        financials?: Array<{
+            label: string;
+            value: string | number;
+        }>;
+        products?: Array<{
+            name: string;
+            description?: string;
+        }>;
+    }): AICardConfig;
+    /**
+     * Create a contact card
+     *
+     * @param options - Contact card options
+     * @returns Contact card configuration
+     */
+    static createContact(options: ContactCardOptions): AICardConfig;
+    /**
+     * Create an analytics dashboard card
+     *
+     * @param options - Analytics dashboard options
+     * @returns Analytics dashboard configuration
+     */
+    static createAnalytics(options: AnalyticsDashboardOptions): AICardConfig;
+    /**
+     * Create a custom card from a template
+     *
+     * @param template - Template function that returns AICardConfig
+     * @returns Card configuration
+     */
+    static createCustom<T extends AICardConfig>(template: (config: Partial<T>) => T, config: Partial<T>): AICardConfig;
+}
+/**
+ * Convenience factory functions (alternative to PresetFactory class)
+ */
+/**
+ * Create a company card (convenience function)
+ */
+declare function createCompanyPreset(options: CompanyCardOptions): AICardConfig;
+/**
+ * Create a contact card (convenience function)
+ */
+declare function createContactPreset(options: ContactCardOptions): AICardConfig;
+/**
+ * Create an analytics dashboard (convenience function)
+ */
+declare function createAnalyticsPreset(options: AnalyticsDashboardOptions): AICardConfig;
+
 interface MasonryLayoutInfo {
     breakpoint: Breakpoint;
     columns: number;
@@ -744,6 +1757,8 @@ declare class AICardRendererComponent implements OnInit, AfterViewInit, OnDestro
     private _cardConfig?;
     private readonly el;
     private readonly cdr;
+    private readonly injector;
+    private readonly platformId;
     Math: Math;
     private previousSectionsHash;
     private normalizedSectionCache;
@@ -885,6 +1900,11 @@ declare class AICardRendererComponent implements OnInit, AfterViewInit, OnDestro
     private mergeWithPreviousOrder;
     private getSectionKey;
     private resetProcessedSections;
+    /**
+     * Validates that animation providers are configured.
+     * Warns in development mode if animations are not available.
+     */
+    private validateAnimationsProvider;
     static ɵfac: i0.ɵɵFactoryDeclaration<AICardRendererComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<AICardRendererComponent, "app-ai-card-renderer", never, { "cardConfig": { "alias": "cardConfig"; "required": false; }; "updateSource": { "alias": "updateSource"; "required": false; }; "isFullscreen": { "alias": "isFullscreen"; "required": false; }; "tiltEnabled": { "alias": "tiltEnabled"; "required": false; }; "streamingStage": { "alias": "streamingStage"; "required": false; }; "streamingProgress": { "alias": "streamingProgress"; "required": false; }; "streamingProgressLabel": { "alias": "streamingProgressLabel"; "required": false; }; "changeType": { "alias": "changeType"; "required": false; }; }, { "fieldInteraction": "fieldInteraction"; "cardInteraction": "cardInteraction"; "fullscreenToggle": "fullscreenToggle"; "agentAction": "agentAction"; "questionAction": "questionAction"; }, never, never, true, never>;
 }
@@ -946,6 +1966,109 @@ declare class CardPreviewComponent implements OnInit, OnChanges, OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<CardPreviewComponent, "app-card-preview", never, { "generatedCard": { "alias": "generatedCard"; "required": false; }; "isGenerating": { "alias": "isGenerating"; "required": false; }; "isInitialized": { "alias": "isInitialized"; "required": false; }; "isFullscreen": { "alias": "isFullscreen"; "required": false; }; }, { "cardInteraction": "cardInteraction"; "fieldInteraction": "fieldInteraction"; "fullscreenToggle": "fullscreenToggle"; "agentAction": "agentAction"; "questionAction": "questionAction"; }, never, never, true, never>;
 }
 
+/**
+ * Card Header Component
+ *
+ * Composable component for rendering card header with title, subtitle, and optional actions.
+ * Can be used independently or as part of the full card renderer.
+ *
+ * @example
+ * ```html
+ * <app-card-header
+ *   [title]="card.cardTitle"
+ *   [subtitle]="card.cardSubtitle"
+ *   [showFullscreenButton]="true"
+ *   [isFullscreen]="false"
+ *   (fullscreenToggle)="onFullscreenToggle($event)">
+ * </app-card-header>
+ * ```
+ */
+declare class CardHeaderComponent {
+    /** Card title */
+    title?: string;
+    /** Card subtitle */
+    subtitle?: string;
+    /** Whether to show fullscreen toggle button */
+    showFullscreenButton: boolean;
+    /** Current fullscreen state */
+    isFullscreen: boolean;
+    /** Emitted when fullscreen button is clicked */
+    fullscreenToggle: EventEmitter<boolean>;
+    onFullscreenClick(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CardHeaderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CardHeaderComponent, "app-card-header", never, { "title": { "alias": "title"; "required": false; }; "subtitle": { "alias": "subtitle"; "required": false; }; "showFullscreenButton": { "alias": "showFullscreenButton"; "required": false; }; "isFullscreen": { "alias": "isFullscreen"; "required": false; }; }, { "fullscreenToggle": "fullscreenToggle"; }, never, never, true, never>;
+}
+
+/**
+ * Card Body Component
+ *
+ * Composable component for rendering card body with sections in a masonry grid layout.
+ * Wraps MasonryGridComponent for easier composition.
+ *
+ * @example
+ * ```html
+ * <app-card-body
+ *   [sections]="card.sections"
+ *   [gap]="12"
+ *   [minColumnWidth]="280"
+ *   (sectionEvent)="onSectionEvent($event)"
+ *   (layoutChange)="onLayoutChange($event)">
+ * </app-card-body>
+ * ```
+ */
+declare class CardBodyComponent {
+    /** Sections to render */
+    sections: CardSection[];
+    /** Gap between grid items in pixels */
+    gap: number;
+    /** Minimum column width in pixels */
+    minColumnWidth: number;
+    /** Emitted when a section event occurs */
+    sectionEvent: EventEmitter<SectionRenderEvent>;
+    /** Emitted when layout changes */
+    layoutChange: EventEmitter<MasonryLayoutInfo>;
+    onSectionEvent(event: SectionRenderEvent): void;
+    onLayoutChange(info: MasonryLayoutInfo): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CardBodyComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CardBodyComponent, "app-card-body", never, { "sections": { "alias": "sections"; "required": false; }; "gap": { "alias": "gap"; "required": false; }; "minColumnWidth": { "alias": "minColumnWidth"; "required": false; }; }, { "sectionEvent": "sectionEvent"; "layoutChange": "layoutChange"; }, never, ["*"], true, never>;
+}
+
+/**
+ * Card Footer Component
+ *
+ * Composable component for rendering card footer with actions and optional signature.
+ * Can be used independently or as part of the full card renderer.
+ *
+ * @example
+ * ```html
+ * <app-card-footer
+ *   [actions]="card.actions"
+ *   [showSignature]="true"
+ *   (actionClick)="onActionClick($event)">
+ * </app-card-footer>
+ * ```
+ */
+declare class CardFooterComponent {
+    /** Actions to display */
+    actions: CardAction[];
+    /** Whether to show the signature */
+    showSignature: boolean;
+    /** Signature text to display */
+    signatureText: string;
+    /** Emitted when an action is clicked */
+    actionClick: EventEmitter<CardAction>;
+    private readonly iconService;
+    get hasActions(): boolean;
+    trackAction(index: number, action: CardAction): string;
+    getActionButtonClasses(action: CardAction): Record<string, boolean>;
+    getActionIconNameForDisplay(action: CardAction): string | null;
+    hasImageIcon(action: CardAction): boolean;
+    hasTextIcon(action: CardAction): boolean;
+    onActionClick(action: CardAction): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CardFooterComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CardFooterComponent, "app-card-footer", never, { "actions": { "alias": "actions"; "required": false; }; "showSignature": { "alias": "showSignature"; "required": false; }; "signatureText": { "alias": "signatureText"; "required": false; }; }, { "actionClick": "actionClick"; }, never, never, true, never>;
+}
+
 type AnalyticsField = CardField & {
     change?: number;
     trend?: 'up' | 'down' | 'stable';
@@ -1302,5 +2425,5 @@ declare class TextReferenceSectionComponent extends BaseSectionComponent<TextRef
     static ɵcmp: i0.ɵɵComponentDeclaration<TextReferenceSectionComponent, "app-text-reference-section", never, {}, {}, never, never, true, never>;
 }
 
-export { AICardRendererComponent, AnalyticsSectionComponent, BaseSectionComponent, BrandColorsSectionComponent, CardDiffUtil, CardPreviewComponent, CardSkeletonComponent, CardTypeGuards, CardUtils, ChartSectionComponent, ContactCardSectionComponent, EventSectionComponent, FallbackSectionComponent, FinancialsSectionComponent, IconService, InfoSectionComponent, ListSectionComponent, LucideIconsModule, MagneticTiltService, MapSectionComponent, MasonryGridComponent, NetworkCardSectionComponent, NewsSectionComponent, OverviewSectionComponent, ProductSectionComponent, QuotationSectionComponent, SectionNormalizationService, SectionRendererComponent, SectionUtilsService, SocialMediaSectionComponent, SolutionsSectionComponent, TextReferenceSectionComponent, getBreakpointFromWidth };
-export type { AICardConfig, AgentCardAction, Breakpoint, CardAction, CardActionButtonType, CardChangeType, CardDiffResult, CardField, CardFieldInteractionEvent, CardItem, CardSection, CardType, EmailConfig, EmailContact, InfoSectionFieldInteraction, LegacyCardAction, MailCardAction, MasonryLayoutInfo, MousePosition, PriorityValue, QuestionCardAction, SectionInteraction, SectionRenderEvent, StatusValue, StreamingStage, TiltCalculations, TrendValue, WebsiteCardAction };
+export { AICardRendererComponent, AnalyticsSectionComponent, BaseSectionComponent, BrandColorsSectionComponent, CardBodyComponent, CardDiffUtil, CardFooterComponent, CardHeaderComponent, CardPreviewComponent, CardSkeletonComponent, CardTypeGuards, CardUtils, ChartSectionComponent, ContactCardSectionComponent, EventMiddlewareService, EventSectionComponent, FallbackSectionComponent, FinancialsSectionComponent, IconService, InfoSectionComponent, ListSectionComponent, LucideIconsModule, MagneticTiltService, MapSectionComponent, MasonryGridComponent, NetworkCardSectionComponent, NewsSectionComponent, OverviewSectionComponent, PresetFactory, ProductSectionComponent, QuotationSectionComponent, SectionNormalizationService, SectionPluginRegistry, SectionRendererComponent, SectionUtilsService, SocialMediaSectionComponent, SolutionsSectionComponent, TextReferenceSectionComponent, ThemeService, areStylesLoaded, buildThemeFromBase, cloneCardConfig, createAnalyticsDashboard, createAnalyticsPreset, createCardFromPartial, createCompanyCard, createCompanyPreset, createContactCard, createContactPreset, createEmptyCard, createEnhancedCompanyCard, createErrorCard, createPartialTheme, createSkeletonCard, darkTheme, generateThemeFromPalette, getBreakpointFromWidth, getCSSVariableValue, highContrastTheme, isCSSVariableDefined, isCardComplete, lightTheme, mergeCardConfig, mergeSections, mergeThemes, prepareCardForStreaming, provideOSICards, updateCardIncremental, validateAndWarnStyles, validateCSSVariableNames, validateCardConfig, validateStyles, waitForStyles };
+export type { AICardConfig, AgentCardAction, AnalyticsDashboardOptions, Breakpoint, CardAction, CardActionButtonType, CardChangeType, CardDiffResult, CardField, CardFieldInteractionEvent, CardItem, CardSection, CardType, CompanyCardOptions, ContactCardOptions, EmailConfig, EmailContact, EventFilter, EventHandler, EventMiddleware, EventTransformer, InfoSectionFieldInteraction, LegacyCardAction, MailCardAction, MasonryLayoutInfo, MousePosition, OSICardsLibConfig, OSICardsThemeConfig, PriorityValue, QuestionCardAction, RegisteredSectionPlugin, SectionInteraction, SectionPlugin, SectionPluginConfig, SectionPluginMetadata, SectionRenderEvent, StatusValue, StreamingStage, StyleValidationResult, ThemePreset, TiltCalculations, TrendValue, WebsiteCardAction };