blacktrigram 0.7.2

package/lib/utils/visualEffects.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Visual Effects Utilities for Korean Cyberpunk Aesthetic
+ *
+ * Provides advanced visual effects for HTML overlay components including:
+ * - Neon glow effects (box-shadow, text-shadow)
+ * - Depth effects (layered shadows, gradients, backdrop-blur)
+ * - Smooth transitions and animations
+ * - Korean font rendering optimization
+ * - Hover and focus state generators
+ *
+ * All effects follow Korean martial arts cyberpunk theme with 60fps performance target.
+ *
+ * @module utils/visualEffects
+ * @category UI Utilities
+ * @korean 시각효과유틸리티
+ */
+/**
+ * Neon glow intensity levels
+ * @korean 네온글로우강도
+ */
+export type GlowIntensity = "subtle" | "medium" | "strong" | "intense";
+/**
+ * Hover state animation types
+ * @korean 호버상태애니메이션
+ */
+export type HoverAnimationType = "glow" | "scale" | "lift" | "pulse" | "combined";
+/**
+ * Transition timing presets
+ * @korean 전환타이밍프리셋
+ */
+export type TransitionTiming = "fast" | "normal" | "slow" | "smooth";
+/**
+ * Depth effect layer configuration
+ * @korean 깊이효과레이어설정
+ */
+export interface DepthEffectConfig {
+    readonly layers: number;
+    readonly baseOffset: number;
+    readonly baseBlur: number;
+    readonly color: number;
+    readonly opacity: number;
+}
+/**
+ * Get neon glow effect CSS string
+ *
+ * Creates cyberpunk-style neon glow using box-shadow with Korean colors.
+ * Supports multiple intensity levels for different UI elements.
+ *
+ * @param color - Hex color value from KOREAN_COLORS
+ * @param intensity - Glow intensity level
+ * @param includeInset - Whether to include inset glow (default: true)
+ * @returns CSS box-shadow string with neon glow effect
+ *
+ * @example
+ * ```typescript
+ * const glow = getNeonGlowEffect(KOREAN_COLORS.PRIMARY_CYAN, 'medium', true);
+ * // Returns: "0 0 20px rgba(0,230,230,0.6), inset 0 0 10px rgba(0,230,230,0.3)"
+ * // Note: Color conversion is handled by hexToRgbaString utility
+ * ```
+ *
+ * @korean 네온글로우효과얻기
+ */
+export declare function getNeonGlowEffect(color: number, intensity?: GlowIntensity, includeInset?: boolean): string;
+/**
+ * Get neon text shadow effect
+ *
+ * Creates glowing text effect for Korean and English text using text-shadow.
+ * Multiple shadow layers create authentic neon glow appearance.
+ *
+ * @param color - Hex color value from KOREAN_COLORS
+ * @param intensity - Glow intensity level
+ * @returns CSS text-shadow string with neon glow
+ *
+ * @example
+ * ```typescript
+ * const textGlow = getNeonTextShadow(KOREAN_COLORS.ACCENT_GOLD, 'strong');
+ * // Returns: "0 0 10px rgba(255,196,0,0.8), 0 0 20px rgba(255,196,0,0.6), 0 0 30px rgba(255,196,0,0.4)"
+ * ```
+ *
+ * @korean 네온텍스트그림자얻기
+ */
+export declare function getNeonTextShadow(color: number, intensity?: GlowIntensity): string;
+/**
+ * Get layered depth effect
+ *
+ * Creates depth using multiple shadow layers with increasing offset and blur.
+ * Provides 3D-like appearance for Korean-themed UI panels.
+ *
+ * @param config - Depth effect configuration
+ * @returns CSS box-shadow string with layered depth
+ *
+ * @example
+ * ```typescript
+ * const depth = getLayeredDepthEffect({
+ *   layers: 3,
+ *   baseOffset: 2,
+ *   baseBlur: 4,
+ *   color: KOREAN_COLORS.BLACK_SOLID,
+ *   opacity: 0.5,
+ * });
+ * ```
+ *
+ * @korean 레이어깊이효과얻기
+ */
+export declare function getLayeredDepthEffect(config: DepthEffectConfig): string;
+/**
+ * Get cyberpunk gradient background
+ *
+ * Creates Korean-themed gradient with cyberpunk colors.
+ * Supports both linear and radial gradients.
+ *
+ * @param primaryColor - Primary hex color
+ * @param secondaryColor - Secondary hex color
+ * @param angle - Gradient angle in degrees (default: 135)
+ * @param type - Gradient type ('linear' | 'radial')
+ * @returns CSS gradient string
+ *
+ * @example
+ * ```typescript
+ * const gradient = getCyberpunkGradient(
+ *   KOREAN_COLORS.PRIMARY_CYAN,
+ *   KOREAN_COLORS.UI_BACKGROUND_DARK,
+ *   135,
+ *   'linear'
+ * );
+ * ```
+ *
+ * @korean 사이버펑크그라디언트얻기
+ */
+export declare function getCyberpunkGradient(primaryColor: number, secondaryColor: number, angle?: number, type?: "linear" | "radial"): string;
+/**
+ * Get smooth transition CSS
+ *
+ * Returns standardized transition string for consistent animations.
+ * All transitions target 60fps performance.
+ *
+ * @param properties - CSS properties to transition (default: 'all')
+ * @param timing - Timing preset
+ * @returns CSS transition string
+ *
+ * @example
+ * ```typescript
+ * const transition = getSmoothTransition('all', 'normal');
+ * // Returns: "all 0.2s ease-in-out"
+ * ```
+ *
+ * @korean 부드러운전환얻기
+ */
+export declare function getSmoothTransition(properties?: string, timing?: TransitionTiming): string;
+/**
+ * Get Korean font optimization styles
+ *
+ * Applies optimal font rendering for Korean characters (Hangul).
+ * Includes anti-aliasing, subpixel rendering, and letter spacing.
+ *
+ * @param fontSize - Font size in pixels
+ * @param fontWeight - Font weight (default: 'normal')
+ * @returns React.CSSProperties with Korean font optimization
+ *
+ * @example
+ * ```typescript
+ * const fontStyle = getKoreanFontOptimization(16, 'bold');
+ * // Returns: { fontSize: '16px', WebkitFontSmoothing: 'antialiased', ... }
+ * ```
+ *
+ * @korean 한글폰트최적화얻기
+ */
+export declare function getKoreanFontOptimization(fontSize: number, fontWeight?: "normal" | "bold"): React.CSSProperties & {
+    WebkitFontSmoothing?: string;
+    MozOsxFontSmoothing?: string;
+};
+/**
+ * Map numeric glow intensity to GlowIntensity type
+ *
+ * Helper to standardize glow intensity mapping across components.
+ * Converts numeric intensity values to discrete levels.
+ *
+ * @param glowIntensity - Numeric glow intensity (0-2+ scale)
+ * @returns GlowIntensity level ("subtle", "medium", "strong", "intense")
+ *
+ * Mapping thresholds:
+ * - intense: >= 1.5
+ * - strong: >= 1.0
+ * - medium: >= 0.6
+ * - subtle: < 0.6
+ *
+ * @example
+ * ```typescript
+ * const level = mapGlowIntensityLevel(0.8);
+ * // Returns: "medium"
+ * mapGlowIntensityLevel(2.0);
+ * // Returns: "intense"
+ * ```
+ *
+ * @korean 광도레벨매핑
+ */
+export declare function mapGlowIntensityLevel(glowIntensity: number): GlowIntensity;
+/**
+ * Get hover state styles with glow effect
+ *
+ * Generates hover state styles with Korean cyberpunk animations.
+ * Includes glow intensification, scale, and lift effects.
+ *
+ * @param baseColor - Base hex color
+ * @param animation - Animation type
+ * @param intensity - Glow intensity for hover state
+ * @returns React.CSSProperties for hover state
+ *
+ * @example
+ * ```typescript
+ * const hoverStyle = getHoverStateStyles(
+ *   KOREAN_COLORS.PRIMARY_CYAN,
+ *   'combined',
+ *   'strong'
+ * );
+ * ```
+ *
+ * @korean 호버상태스타일얻기
+ */
+export declare function getHoverStateStyles(baseColor: number, animation?: HoverAnimationType, intensity?: GlowIntensity): React.CSSProperties;
+/**
+ * Get focus state styles with accessibility
+ *
+ * Creates WCAG-compliant focus indicators with Korean cyberpunk styling.
+ * Ensures 2px border with high contrast (4.5:1 minimum).
+ *
+ * Note: While outline is set to "none", the custom 2px border provides
+ * equivalent accessibility. For users relying on high-contrast mode or
+ * custom browser settings, consider using outline-offset as an additional
+ * fallback or ensure the custom border has sufficient contrast (4.5:1+).
+ *
+ * @param color - Hex color for focus indicator
+ * @param includeGlow - Whether to include glow effect (default: true)
+ * @returns React.CSSProperties for focus state
+ *
+ * @example
+ * ```typescript
+ * const focusStyle = getFocusStateStyles(KOREAN_COLORS.ACCENT_GOLD, true);
+ * ```
+ *
+ * @korean 포커스상태스타일얻기
+ */
+export declare function getFocusStateStyles(color: number, includeGlow?: boolean): React.CSSProperties;
+/**
+ * Get backdrop blur effect
+ *
+ * Creates frosted glass effect for Korean-themed overlays.
+ * GPU-accelerated for 60fps performance.
+ *
+ * @param blurAmount - Blur amount in pixels (default: 10)
+ * @param saturation - Color saturation multiplier (default: 1.5)
+ * @returns React.CSSProperties with backdrop blur
+ *
+ * @example
+ * ```typescript
+ * const backdropStyle = getBackdropBlurEffect(12, 1.8);
+ * ```
+ *
+ * @korean 배경블러효과얻기
+ */
+export declare function getBackdropBlurEffect(blurAmount?: number, saturation?: number): React.CSSProperties & {
+    WebkitBackdropFilter?: string;
+};
+/**
+ * Get trigram symbol glow effect
+ *
+ * Creates glowing effect for Eight Trigram symbols (☰☱☲☳☴☵☶☷).
+ * Uses stance-specific colors from KOREAN_COLORS.
+ *
+ * @param trigramColor - Trigram-specific hex color
+ * @param isActive - Whether trigram is currently active
+ * @returns React.CSSProperties with trigram glow
+ *
+ * @example
+ * ```typescript
+ * const trigramGlow = getTrigramSymbolGlow(
+ *   KOREAN_COLORS.TRIGRAM_GEON_PRIMARY,
+ *   true
+ * );
+ * ```
+ *
+ * @korean 팔괘상징글로우얻기
+ */
+export declare function getTrigramSymbolGlow(trigramColor: number, isActive: boolean): React.CSSProperties;
+/**
+ * Get GPU-accelerated animation hint
+ *
+ * Applies will-change CSS property to hint GPU acceleration.
+ * Use sparingly - only for actively animating elements.
+ *
+ * @param properties - Properties that will animate
+ * @returns React.CSSProperties with GPU hints
+ *
+ * @example
+ * ```typescript
+ * const gpuHint = getGPUAccelerationHint('transform, opacity');
+ * ```
+ *
+ * @korean GPU가속힌트얻기
+ */
+export declare function getGPUAccelerationHint(properties?: string): React.CSSProperties;
+/**
+ * Combine multiple shadow effects
+ *
+ * Merges multiple box-shadow strings into a single CSS value.
+ * Useful for combining glow, depth, and custom shadows.
+ *
+ * @param shadows - Array of box-shadow strings
+ * @returns Combined box-shadow CSS string
+ *
+ * @example
+ * ```typescript
+ * const combined = combineShadowEffects([
+ *   getNeonGlowEffect(KOREAN_COLORS.PRIMARY_CYAN, 'medium'),
+ *   getLayeredDepthEffect({ layers: 2, baseOffset: 2, baseBlur: 4, color: 0x000000, opacity: 0.5 })
+ * ]);
+ * ```
+ *
+ * @korean 그림자효과결합
+ */
+export declare function combineShadowEffects(shadows: string[]): string;
+/**
+ * Get pulsing animation keyframes
+ *
+ * Returns CSS keyframe animation for pulsing glow effect.
+ * Should be injected into global styles or style tag once.
+ * Use unique animation names to avoid conflicts.
+ *
+ * @param animationName - Unique name for the animation (default: 'pulse')
+ * @returns CSS keyframes string
+ *
+ * @example
+ * ```typescript
+ * const keyframes = getPulsingKeyframes('pulse-glow');
+ * // Inject into global styles once:
+ * const style = document.createElement('style');
+ * style.innerHTML = keyframes;
+ * document.head.appendChild(style);
+ * ```
+ *
+ * @warning SSR and Duplicate Keyframes
+ * When using this in Server-Side Rendering (SSR) environments or with multiple
+ * component instances, ensure keyframe definitions are registered globally only once.
+ * Consider using a global registry or checking for existing keyframe definitions
+ * before injection to prevent duplicates and hydration mismatches. Example:
+ * ```typescript
+ * if (!document.querySelector(`style[data-keyframe="${animationName}"]`)) {
+ *   const style = document.createElement('style');
+ *   style.setAttribute('data-keyframe', animationName);
+ *   style.innerHTML = getPulsingKeyframes(animationName);
+ *   document.head.appendChild(style);
+ * }
+ * ```
+ *
+ * @korean 펄스애니메이션키프레임얻기
+ */
+export declare function getPulsingKeyframes(animationName?: string): string;
+//# sourceMappingURL=visualEffects.d.ts.map

package/lib/utils/visualEffects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualEffects.d.ts","sourceRoot":"","sources":["../../src/utils/visualEffects.ts"],"names":[],"mappings":"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"}