keyboard/Shared/KBSkinManager.h

//
//  KBSkinManager.h
//  App & Keyboard Extension shared skin/theme manager.
//
//  Stores a lightweight theme (colors, identifiers) to shared keychain so
//  both targets see the same current skin. Cross-process updates are delivered
//  via Darwin notification. Intended for immediate reflection in extension.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>

NS_ASSUME_NONNULL_BEGIN

extern NSString * const KBSkinDidChangeNotification; // in-process
extern NSString * const KBDarwinSkinChanged;         // cross-process

/// Simple theme model (colors only; assets can be added later via App Group)
@interface KBSkinTheme : NSObject <NSSecureCoding>
@property (nonatomic, copy) NSString *skinId;           // e.g. "mint"
@property (nonatomic, copy) NSString *name;             // display name
@property (nonatomic, strong) UIColor *keyboardBackground;
@property (nonatomic, strong) UIColor *keyBackground;
@property (nonatomic, strong) UIColor *keyTextColor;
@property (nonatomic, strong) UIColor *keyHighlightBackground; // selected/highlighted
@property (nonatomic, strong) UIColor *accentColor;     // function view accents
/// 可选：键盘背景图片的 PNG/JPEG 数据（若存在，优先显示图片）
@property (nonatomic, strong, nullable) NSData *backgroundImageData;
/// 可选：需要隐藏文字的按键标识集合（例如 @"letter_q" @"space" 等）
@property (nonatomic, strong, nullable) NSArray<NSString *> *hiddenKeyTextIdentifiers;
/// 可选：按键图标映射（按键标识 -> 图标名或路径），具体加载策略由上层决定
@property (nonatomic, strong, nullable) NSDictionary<NSString *, NSString *> *keyIconMap;
@end

/// Shared skin manager (Keychain Sharing based)
@interface KBSkinManager : NSObject

+ (instancetype)shared;

@property (atomic, strong, readonly) KBSkinTheme *current; // never nil (fallback to default)

/// Save theme from JSON dictionary (keys: id, name, background, key_bg, key_text, key_highlight, accent)
- (BOOL)applyThemeFromJSON:(NSDictionary *)json;

/// Save explicit theme
- (BOOL)applyTheme:(KBSkinTheme *)theme;

/// Reset to default theme
- (void)resetToDefault;

/// 直接应用图片皮肤（使用 JPEG/PNG 数据）。建议大小 < 512KB。
- (BOOL)applyImageSkinWithData:(NSData *)imageData skinId:(NSString *)skinId name:(NSString *)name;

/// 当前背景图片（若存在）
- (nullable UIImage *)currentBackgroundImage;

/// 当前主题下，指定按键标识的文字是否应被隐藏（例如图标里已包含字母）
- (BOOL)shouldHideKeyTextForIdentifier:(nullable NSString *)identifier;

/// 当前主题下，指定按键标识对应的图标名（可作为 imageName 或文件相对路径），若未配置则为 nil
- (nullable NSString *)iconNameForKeyIdentifier:(nullable NSString *)identifier;

/// 当前主题下，返回指定按键的图标图片。
/// 若 keyIconMap 中的 value 不包含 "/"，则按本地 Assets 名称加载；
/// 若包含 "/"，则视为相对 App Group 根目录的文件路径，从文件系统加载。
- (nullable UIImage *)iconImageForKeyIdentifier:(nullable NSString *)identifier;

/// 带大小写变体的按键图标获取接口。
/// @param identifier 逻辑按键标识（如 @"letter_q" @"space"）
/// @param caseVariant 0=无变体/非字母，1=小写，2=大写（与 KBKeyCaseVariant 对应）
- (nullable UIImage *)iconImageForKeyIdentifier:(nullable NSString *)identifier
                                     caseVariant:(NSInteger)caseVariant;

/// Parse a hex color string like "#RRGGBB"/"#RRGGBBAA"
+ (UIColor *)colorFromHexString:(NSString *)hex defaultColor:(UIColor *)fallback;

@end

NS_ASSUME_NONNULL_END