@djangocfg/ui-core 2.1.102 → 2.1.103

package/dist/hooks.d.mts

@@ -0,0 +1,190 @@
+import { toast } from 'sonner';
+export { toast } from 'sonner';
+
+interface CountdownState {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    isExpired: boolean;
+    totalSeconds: number;
+}
+declare const useCountdown: (targetDate: string | null) => CountdownState;
+
+/**
+ * Creates a debounced version of a callback function.
+ *
+ * @param callback The function to debounce.
+ * @param delay The debounce delay in milliseconds.
+ * @returns A debounced callback function.
+ */
+declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay: number): (...args: Parameters<T>) => void;
+
+/**
+ * useDebounce hook
+ *
+ * Debounces a value by delaying its update until after a specified delay.
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+type DebugValue = Record<string, unknown> | unknown[] | null | undefined;
+declare function useDebugTools(values: DebugValue, prefix?: string): void;
+
+type FormEvent<T extends string = string, P = any> = {
+    type: T;
+    payload?: P;
+    timestamp?: number;
+};
+type EventListener<T extends FormEvent> = (event: T) => void;
+declare class EventBus {
+    private listeners;
+    publish<T extends FormEvent>(event: T): void;
+    subscribe<T extends FormEvent>(listener: EventListener<T>): () => void;
+}
+declare const events: EventBus;
+declare function useEventListener<T extends string, P>(eventType: T, handler: (payload: P) => void): void;
+
+declare function useIsMobile(): boolean;
+
+/**
+ * Hook to check if a media query matches
+ *
+ * @param query - CSS media query string
+ * @returns boolean indicating if the query matches
+ *
+ * @example
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+ * const isLandscape = useMediaQuery('(orientation: landscape)');
+ */
+declare function useMediaQuery(query: string): boolean;
+
+interface UseCopyOptions {
+    successMessage?: string;
+    errorMessage?: string;
+}
+declare const useCopy: (options?: UseCopyOptions) => {
+    copyToClipboard: (text: string, customSuccessMessage?: string) => Promise<boolean>;
+};
+
+/**
+ * Enhanced Image Loader Hook
+ *
+ * Hook to check if an image is loaded successfully with callback support
+ */
+interface ImageLoaderState {
+    isLoading: boolean;
+    isLoaded: boolean;
+    hasError: boolean;
+}
+interface ImageLoaderCallbacks {
+    onLoadStart?: () => void;
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+}
+declare const useImageLoader: (src?: string, callbacks?: ImageLoaderCallbacks) => ImageLoaderState;
+
+/**
+ * Toast notifications using Sonner
+ *
+ * @example
+ * import { toast } from '@djangocfg/ui-core/hooks';
+ *
+ * toast.success('Saved!');
+ * toast.error('Error', { description: 'Details here' });
+ * toast.promise(fetchData(), { loading: 'Loading...', success: 'Done!', error: 'Failed' });
+ */
+
+type ToastFn = typeof toast;
+declare function useToast(): {
+    toast: ToastFn;
+    dismiss: ToastFn['dismiss'];
+};
+
+type ResolvedTheme = 'light' | 'dark';
+/**
+ * Hook to detect the current resolved theme (light or dark)
+ *
+ * Standalone hook - doesn't require ThemeProvider.
+ * Detects theme from:
+ * 1. 'dark' class on html element
+ * 2. System preference (prefers-color-scheme)
+ *
+ * For full theme control (setTheme, toggleTheme), use useThemeContext instead.
+ *
+ * @example
+ * ```tsx
+ * const theme = useResolvedTheme(); // 'light' | 'dark'
+ * ```
+ */
+declare const useResolvedTheme: () => ResolvedTheme;
+
+/**
+ * Options for useLocalStorage hook
+ */
+interface UseLocalStorageOptions {
+    /**
+     * Time-to-live in milliseconds.
+     * After this time, value is considered expired and initialValue is returned.
+     * Data is automatically cleaned up on next read.
+     * @example 24 * 60 * 60 * 1000 // 24 hours
+     */
+    ttl?: number;
+}
+/**
+ * Simple localStorage hook with better error handling and optional TTL support
+ *
+ * IMPORTANT: To prevent hydration mismatch, this hook:
+ * - Always returns initialValue on first render (same as SSR)
+ * - Reads from localStorage only after component mounts
+ *
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useLocalStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (24 hours)
+ * const [value, setValue] = useLocalStorage('key', 'default', {
+ *   ttl: 24 * 60 * 60 * 1000
+ * });
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+/**
+ * Options for useSessionStorage hook
+ */
+interface UseSessionStorageOptions {
+    /**
+     * Time-to-live in milliseconds.
+     * After this time, value is considered expired and initialValue is returned.
+     * Data is automatically cleaned up on next read.
+     * @example 24 * 60 * 60 * 1000 // 24 hours
+     */
+    ttl?: number;
+}
+/**
+ * Simple sessionStorage hook with better error handling and optional TTL support
+ *
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useSessionStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (1 hour)
+ * const [value, setValue] = useSessionStorage('key', 'default', {
+ *   ttl: 60 * 60 * 1000
+ * });
+ */
+declare function useSessionStorage<T>(key: string, initialValue: T, options?: UseSessionStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+export { type ResolvedTheme, events, useCopy, useCountdown, useDebounce, useDebouncedCallback, useDebugTools, useEventListener, useImageLoader, useIsMobile, useLocalStorage, useMediaQuery, useResolvedTheme, useSessionStorage, useToast };

package/dist/hooks.d.ts

@@ -0,0 +1,190 @@
+import { toast } from 'sonner';
+export { toast } from 'sonner';
+
+interface CountdownState {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    isExpired: boolean;
+    totalSeconds: number;
+}
+declare const useCountdown: (targetDate: string | null) => CountdownState;
+
+/**
+ * Creates a debounced version of a callback function.
+ *
+ * @param callback The function to debounce.
+ * @param delay The debounce delay in milliseconds.
+ * @returns A debounced callback function.
+ */
+declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay: number): (...args: Parameters<T>) => void;
+
+/**
+ * useDebounce hook
+ *
+ * Debounces a value by delaying its update until after a specified delay.
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+type DebugValue = Record<string, unknown> | unknown[] | null | undefined;
+declare function useDebugTools(values: DebugValue, prefix?: string): void;
+
+type FormEvent<T extends string = string, P = any> = {
+    type: T;
+    payload?: P;
+    timestamp?: number;
+};
+type EventListener<T extends FormEvent> = (event: T) => void;
+declare class EventBus {
+    private listeners;
+    publish<T extends FormEvent>(event: T): void;
+    subscribe<T extends FormEvent>(listener: EventListener<T>): () => void;
+}
+declare const events: EventBus;
+declare function useEventListener<T extends string, P>(eventType: T, handler: (payload: P) => void): void;
+
+declare function useIsMobile(): boolean;
+
+/**
+ * Hook to check if a media query matches
+ *
+ * @param query - CSS media query string
+ * @returns boolean indicating if the query matches
+ *
+ * @example
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+ * const isLandscape = useMediaQuery('(orientation: landscape)');
+ */
+declare function useMediaQuery(query: string): boolean;
+
+interface UseCopyOptions {
+    successMessage?: string;
+    errorMessage?: string;
+}
+declare const useCopy: (options?: UseCopyOptions) => {
+    copyToClipboard: (text: string, customSuccessMessage?: string) => Promise<boolean>;
+};
+
+/**
+ * Enhanced Image Loader Hook
+ *
+ * Hook to check if an image is loaded successfully with callback support
+ */
+interface ImageLoaderState {
+    isLoading: boolean;
+    isLoaded: boolean;
+    hasError: boolean;
+}
+interface ImageLoaderCallbacks {
+    onLoadStart?: () => void;
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+}
+declare const useImageLoader: (src?: string, callbacks?: ImageLoaderCallbacks) => ImageLoaderState;
+
+/**
+ * Toast notifications using Sonner
+ *
+ * @example
+ * import { toast } from '@djangocfg/ui-core/hooks';
+ *
+ * toast.success('Saved!');
+ * toast.error('Error', { description: 'Details here' });
+ * toast.promise(fetchData(), { loading: 'Loading...', success: 'Done!', error: 'Failed' });
+ */
+
+type ToastFn = typeof toast;
+declare function useToast(): {
+    toast: ToastFn;
+    dismiss: ToastFn['dismiss'];
+};
+
+type ResolvedTheme = 'light' | 'dark';
+/**
+ * Hook to detect the current resolved theme (light or dark)
+ *
+ * Standalone hook - doesn't require ThemeProvider.
+ * Detects theme from:
+ * 1. 'dark' class on html element
+ * 2. System preference (prefers-color-scheme)
+ *
+ * For full theme control (setTheme, toggleTheme), use useThemeContext instead.
+ *
+ * @example
+ * ```tsx
+ * const theme = useResolvedTheme(); // 'light' | 'dark'
+ * ```
+ */
+declare const useResolvedTheme: () => ResolvedTheme;
+
+/**
+ * Options for useLocalStorage hook
+ */
+interface UseLocalStorageOptions {
+    /**
+     * Time-to-live in milliseconds.
+     * After this time, value is considered expired and initialValue is returned.
+     * Data is automatically cleaned up on next read.
+     * @example 24 * 60 * 60 * 1000 // 24 hours
+     */
+    ttl?: number;
+}
+/**
+ * Simple localStorage hook with better error handling and optional TTL support
+ *
+ * IMPORTANT: To prevent hydration mismatch, this hook:
+ * - Always returns initialValue on first render (same as SSR)
+ * - Reads from localStorage only after component mounts
+ *
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useLocalStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (24 hours)
+ * const [value, setValue] = useLocalStorage('key', 'default', {
+ *   ttl: 24 * 60 * 60 * 1000
+ * });
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+/**
+ * Options for useSessionStorage hook
+ */
+interface UseSessionStorageOptions {
+    /**
+     * Time-to-live in milliseconds.
+     * After this time, value is considered expired and initialValue is returned.
+     * Data is automatically cleaned up on next read.
+     * @example 24 * 60 * 60 * 1000 // 24 hours
+     */
+    ttl?: number;
+}
+/**
+ * Simple sessionStorage hook with better error handling and optional TTL support
+ *
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useSessionStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (1 hour)
+ * const [value, setValue] = useSessionStorage('key', 'default', {
+ *   ttl: 60 * 60 * 1000
+ * });
+ */
+declare function useSessionStorage<T>(key: string, initialValue: T, options?: UseSessionStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+export { type ResolvedTheme, events, useCopy, useCountdown, useDebounce, useDebouncedCallback, useDebugTools, useEventListener, useImageLoader, useIsMobile, useLocalStorage, useMediaQuery, useResolvedTheme, useSessionStorage, useToast };

package/dist/lib.d.mts

@@ -0,0 +1,206 @@
+import { ClassValue } from 'clsx';
+import * as zustand from 'zustand';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * OG Image URL Generation Utilities
+ *
+ * Client-side utilities for generating OG image URLs.
+ */
+/**
+ * OG Image URL parameters
+ */
+interface OgImageUrlParams {
+    /** Page title */
+    title: string;
+    /** Page description (optional) */
+    description?: string;
+    /** Site name (optional) */
+    siteName?: string;
+    /** Logo URL (optional) */
+    logo?: string;
+    /** Background type: 'gradient' or 'solid' */
+    backgroundType?: 'gradient' | 'solid';
+    /** Gradient start color (hex) */
+    gradientStart?: string;
+    /** Gradient end color (hex) */
+    gradientEnd?: string;
+    /** Background color (for solid type) */
+    backgroundColor?: string;
+    /** Title font size (px) */
+    titleSize?: number;
+    /** Title font weight */
+    titleWeight?: number;
+    /** Title text color */
+    titleColor?: string;
+    /** Description font size (px) */
+    descriptionSize?: number;
+    /** Description text color */
+    descriptionColor?: string;
+    /** Site name font size (px) */
+    siteNameSize?: number;
+    /** Site name text color */
+    siteNameColor?: string;
+    /** Padding (px) */
+    padding?: number;
+    /** Logo size (px) */
+    logoSize?: number;
+    /** Show logo flag */
+    showLogo?: boolean;
+    /** Show site name flag */
+    showSiteName?: boolean;
+    /** Additional custom parameters */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Options for generating OG image URL
+ */
+interface GenerateOgImageUrlOptions {
+    /**
+     * Base URL of the OG image API route
+     * @default 'https://djangocfg.com/api/og'
+     */
+    baseUrl?: string;
+    /**
+     * If true, encode params as base64 for safer URLs
+     * @default true
+     */
+    useBase64?: boolean;
+}
+/**
+ * Generate OG image URL with query parameters or base64 encoding
+ *
+ * @example
+ * ```typescript
+ * // Using default baseUrl (https://djangocfg.com/api/og)
+ * const url = generateOgImageUrl({ title: 'My Page Title' });
+ *
+ * // With custom baseUrl
+ * const url = generateOgImageUrl({ title: 'My Page' }, { baseUrl: '/api/og' });
+ * ```
+ */
+declare function generateOgImageUrl(params: OgImageUrlParams, options?: GenerateOgImageUrlOptions): string;
+/**
+ * Get absolute OG image URL from relative path
+ */
+declare function getAbsoluteOgImageUrl(relativePath: string, siteUrl: string): string;
+/**
+ * Create OG image URL builder with preset configuration
+ */
+declare function createOgImageUrlBuilder(defaults?: Partial<OgImageUrlParams>, options?: GenerateOgImageUrlOptions): (params: OgImageUrlParams) => string;
+
+/**
+ * Logger Types
+ *
+ * Type definitions for the universal logging system.
+ * Compatible with Console panel in FileWorkspace IDE layout.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success';
+interface LogEntry {
+    /** Unique log ID */
+    id: string;
+    /** Timestamp when log was created */
+    timestamp: Date;
+    /** Log level */
+    level: LogLevel;
+    /** Component/module name that created the log */
+    component: string;
+    /** Log message */
+    message: string;
+    /** Additional data (objects, errors, etc.) */
+    data?: Record<string, unknown>;
+    /** Error stack trace (for error level) */
+    stack?: string;
+}
+interface LogFilter {
+    /** Filter by log levels */
+    levels: LogLevel[];
+    /** Filter by component name (partial match) */
+    component?: string;
+    /** Filter by message text (partial match) */
+    search?: string;
+    /** Filter by time range */
+    since?: Date;
+}
+interface LogStore {
+    /** All accumulated logs */
+    logs: LogEntry[];
+    /** Current filter settings */
+    filter: LogFilter;
+    /** Maximum logs to keep */
+    maxLogs: number;
+    /** Add new log entry */
+    addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+    /** Clear all logs */
+    clearLogs: () => void;
+    /** Update filter settings */
+    setFilter: (filter: Partial<LogFilter>) => void;
+    /** Reset filter to defaults */
+    resetFilter: () => void;
+    /** Get filtered logs */
+    getFilteredLogs: () => LogEntry[];
+    /** Export logs as JSON string */
+    exportLogs: () => string;
+}
+interface Logger {
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    success: (message: string, data?: Record<string, unknown>) => void;
+}
+/**
+ * Media-specific log helper methods
+ */
+interface MediaLogger extends Logger {
+    /** Log source load event */
+    load: (src: string, type?: string) => void;
+    /** Log state change */
+    state: (state: string, details?: Record<string, unknown>) => void;
+    /** Log seek event */
+    seek: (from: number, to: number, duration: number) => void;
+    /** Log buffer ranges */
+    buffer: (buffered: TimeRanges, duration: number) => void;
+    /** Log generic event */
+    event: (name: string, data?: unknown) => void;
+}
+
+/**
+ * Logger
+ *
+ * Universal logger with consola + zustand store integration.
+ * Logs are accumulated for Console panel display.
+ * In production, only logs to store (no console output).
+ */
+
+/**
+ * Create a logger for a specific component/module
+ */
+declare function createLogger(component: string): Logger;
+/**
+ * Create a media-specific logger with helper methods
+ * for AudioPlayer, VideoPlayer, ImageViewer
+ */
+declare function createMediaLogger(component: string): MediaLogger;
+/**
+ * Global logger for non-component code
+ */
+declare const logger: Logger;
+/**
+ * Quick access for one-off logs
+ */
+declare const log: {
+    debug: (component: string, message: string, data?: Record<string, unknown>) => void;
+    info: (component: string, message: string, data?: Record<string, unknown>) => void;
+    warn: (component: string, message: string, data?: Record<string, unknown>) => void;
+    error: (component: string, message: string, data?: Record<string, unknown>) => void;
+    success: (component: string, message: string, data?: Record<string, unknown>) => void;
+};
+
+declare const useLogStore: zustand.UseBoundStore<zustand.StoreApi<LogStore>>;
+declare const useFilteredLogs: () => LogEntry[];
+declare const useLogCount: () => number;
+declare const useErrorCount: () => number;
+
+export { type GenerateOgImageUrlOptions, type LogEntry, type LogFilter, type LogLevel, type LogStore, type Logger, type MediaLogger, type OgImageUrlParams, cn, createLogger, createMediaLogger, createOgImageUrlBuilder, generateOgImageUrl, getAbsoluteOgImageUrl, log, logger, useErrorCount, useFilteredLogs, useLogCount, useLogStore };

package/dist/lib.d.ts

@@ -0,0 +1,206 @@
+import { ClassValue } from 'clsx';
+import * as zustand from 'zustand';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * OG Image URL Generation Utilities
+ *
+ * Client-side utilities for generating OG image URLs.
+ */
+/**
+ * OG Image URL parameters
+ */
+interface OgImageUrlParams {
+    /** Page title */
+    title: string;
+    /** Page description (optional) */
+    description?: string;
+    /** Site name (optional) */
+    siteName?: string;
+    /** Logo URL (optional) */
+    logo?: string;
+    /** Background type: 'gradient' or 'solid' */
+    backgroundType?: 'gradient' | 'solid';
+    /** Gradient start color (hex) */
+    gradientStart?: string;
+    /** Gradient end color (hex) */
+    gradientEnd?: string;
+    /** Background color (for solid type) */
+    backgroundColor?: string;
+    /** Title font size (px) */
+    titleSize?: number;
+    /** Title font weight */
+    titleWeight?: number;
+    /** Title text color */
+    titleColor?: string;
+    /** Description font size (px) */
+    descriptionSize?: number;
+    /** Description text color */
+    descriptionColor?: string;
+    /** Site name font size (px) */
+    siteNameSize?: number;
+    /** Site name text color */
+    siteNameColor?: string;
+    /** Padding (px) */
+    padding?: number;
+    /** Logo size (px) */
+    logoSize?: number;
+    /** Show logo flag */
+    showLogo?: boolean;
+    /** Show site name flag */
+    showSiteName?: boolean;
+    /** Additional custom parameters */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Options for generating OG image URL
+ */
+interface GenerateOgImageUrlOptions {
+    /**
+     * Base URL of the OG image API route
+     * @default 'https://djangocfg.com/api/og'
+     */
+    baseUrl?: string;
+    /**
+     * If true, encode params as base64 for safer URLs
+     * @default true
+     */
+    useBase64?: boolean;
+}
+/**
+ * Generate OG image URL with query parameters or base64 encoding
+ *
+ * @example
+ * ```typescript
+ * // Using default baseUrl (https://djangocfg.com/api/og)
+ * const url = generateOgImageUrl({ title: 'My Page Title' });
+ *
+ * // With custom baseUrl
+ * const url = generateOgImageUrl({ title: 'My Page' }, { baseUrl: '/api/og' });
+ * ```
+ */
+declare function generateOgImageUrl(params: OgImageUrlParams, options?: GenerateOgImageUrlOptions): string;
+/**
+ * Get absolute OG image URL from relative path
+ */
+declare function getAbsoluteOgImageUrl(relativePath: string, siteUrl: string): string;
+/**
+ * Create OG image URL builder with preset configuration
+ */
+declare function createOgImageUrlBuilder(defaults?: Partial<OgImageUrlParams>, options?: GenerateOgImageUrlOptions): (params: OgImageUrlParams) => string;
+
+/**
+ * Logger Types
+ *
+ * Type definitions for the universal logging system.
+ * Compatible with Console panel in FileWorkspace IDE layout.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success';
+interface LogEntry {
+    /** Unique log ID */
+    id: string;
+    /** Timestamp when log was created */
+    timestamp: Date;
+    /** Log level */
+    level: LogLevel;
+    /** Component/module name that created the log */
+    component: string;
+    /** Log message */
+    message: string;
+    /** Additional data (objects, errors, etc.) */
+    data?: Record<string, unknown>;
+    /** Error stack trace (for error level) */
+    stack?: string;
+}
+interface LogFilter {
+    /** Filter by log levels */
+    levels: LogLevel[];
+    /** Filter by component name (partial match) */
+    component?: string;
+    /** Filter by message text (partial match) */
+    search?: string;
+    /** Filter by time range */
+    since?: Date;
+}
+interface LogStore {
+    /** All accumulated logs */
+    logs: LogEntry[];
+    /** Current filter settings */
+    filter: LogFilter;
+    /** Maximum logs to keep */
+    maxLogs: number;
+    /** Add new log entry */
+    addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+    /** Clear all logs */
+    clearLogs: () => void;
+    /** Update filter settings */
+    setFilter: (filter: Partial<LogFilter>) => void;
+    /** Reset filter to defaults */
+    resetFilter: () => void;
+    /** Get filtered logs */
+    getFilteredLogs: () => LogEntry[];
+    /** Export logs as JSON string */
+    exportLogs: () => string;
+}
+interface Logger {
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    success: (message: string, data?: Record<string, unknown>) => void;
+}
+/**
+ * Media-specific log helper methods
+ */
+interface MediaLogger extends Logger {
+    /** Log source load event */
+    load: (src: string, type?: string) => void;
+    /** Log state change */
+    state: (state: string, details?: Record<string, unknown>) => void;
+    /** Log seek event */
+    seek: (from: number, to: number, duration: number) => void;
+    /** Log buffer ranges */
+    buffer: (buffered: TimeRanges, duration: number) => void;
+    /** Log generic event */
+    event: (name: string, data?: unknown) => void;
+}
+
+/**
+ * Logger
+ *
+ * Universal logger with consola + zustand store integration.
+ * Logs are accumulated for Console panel display.
+ * In production, only logs to store (no console output).
+ */
+
+/**
+ * Create a logger for a specific component/module
+ */
+declare function createLogger(component: string): Logger;
+/**
+ * Create a media-specific logger with helper methods
+ * for AudioPlayer, VideoPlayer, ImageViewer
+ */
+declare function createMediaLogger(component: string): MediaLogger;
+/**
+ * Global logger for non-component code
+ */
+declare const logger: Logger;
+/**
+ * Quick access for one-off logs
+ */
+declare const log: {
+    debug: (component: string, message: string, data?: Record<string, unknown>) => void;
+    info: (component: string, message: string, data?: Record<string, unknown>) => void;
+    warn: (component: string, message: string, data?: Record<string, unknown>) => void;
+    error: (component: string, message: string, data?: Record<string, unknown>) => void;
+    success: (component: string, message: string, data?: Record<string, unknown>) => void;
+};
+
+declare const useLogStore: zustand.UseBoundStore<zustand.StoreApi<LogStore>>;
+declare const useFilteredLogs: () => LogEntry[];
+declare const useLogCount: () => number;
+declare const useErrorCount: () => number;
+
+export { type GenerateOgImageUrlOptions, type LogEntry, type LogFilter, type LogLevel, type LogStore, type Logger, type MediaLogger, type OgImageUrlParams, cn, createLogger, createMediaLogger, createOgImageUrlBuilder, generateOgImageUrl, getAbsoluteOgImageUrl, log, logger, useErrorCount, useFilteredLogs, useLogCount, useLogStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.102",
+  "version": "2.1.103",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -125,7 +125,7 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.102",
+    "@djangocfg/typescript-config": "^2.1.103",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",