//
//  GSPaletteColor.h
//  GlyphsCore
//
//  Created by Florian Pircher on 17.01.25.
//  Copyright © 2025 schriftgestaltung.de. All rights reserved.
//

#import <GlyphsCore/GSBase.h>
#import <GlyphsCore/GSDrawEnvironment.h>

NS_ASSUME_NONNULL_BEGIN

static const uint16_t kGSPaletteColorTextColorIndex NS_SWIFT_NAME(GSPaletteColor.textColorIndex) = 0xFFFF;

/// A color that references a base color from a color palette and multiplies the alpha component with an additional factor.
///
/// Before using the color, update effective color values using ``updateForEnvironment:``.
/// A palette color with an invalid palette container or color index renders as ``NSColor/errorReplacementColor`` (bright pink).
///
/// Palette colors are not immutable, as changes to the referenced palette affect the value of the color.
/// Access must happen on the main thread.
@interface GSPaletteColor : NSColor

/// The index into a color palette referencing the base color.
@property (assign) uint16_t colorIndex;
/// A factor that is multiplied with the alpha component of the base color to create the effective color.
@property (assign) CGFloat alphaFactor;
/// Resolves the palette color to a regular color object.
///
/// The color is resolved with respect to the current drawing appearance.
///
/// The color performs functionally equivalent to the palette color except that it immutable.
/// That is, modifications to the color palette do not affect the returned color.
@property (nonatomic, readonly) NSColor *effectiveColor NS_SWIFT_UI_ACTOR;
/// Resolves the palette color to a regular color object.
///
/// The color is resolved with respect to the given setting.
///
/// The color performs functionally equivalent to the palette color except that it immutable.
/// That is, modifications to the color palette do not affect the returned color.
- (NSColor *)effectiveColorInSetting:(GSDrawEnvironmentSetting)setting NS_SWIFT_UI_ACTOR;

/// Dynamic color that adapts to the user-selected foreground color.
///
/// Before using the color, update its effective color values using ``updateForEnvironment:``.
@property (class, readonly, nonatomic) GSPaletteColor *textColor;

/// Creates a palette color.
///
/// When the `environment` does not provide sufficient informations, the effective color values are set to ``NSColor/errorReplacementColor``.
- (instancetype)initWithIndex:(uint16_t)index alphaFactor:(CGFloat)alphaFactor environment:(nullable GSDrawEnvironment *)environment NS_DESIGNATED_INITIALIZER;
/// Creates a palette color.
///
/// The initial effective color for all settings is the given base color, or ``NSColor/errorReplacementColor``.
- (instancetype)initWithIndex:(uint16_t)index alphaFactor:(CGFloat)alphaFactor baseColor:(nullable NSColor *)baseColor NS_DESIGNATED_INITIALIZER;

/// Dynamic color that adapts to the user-selected foreground color.
///
/// Before using the color, update its effective color values using ``updateForEnvironment:``.
+ (instancetype)textColorWithAlphaComponent:(CGFloat)alphaComponent;

/// Updates the effective color values of the palette color to match the given environment.
///
/// When the `environment` does not provide sufficient informations, the effective color values are set to ``NSColor/errorReplacementColor``.
- (void)updateForEnvironment:(nullable GSDrawEnvironment *)environment NS_SWIFT_UI_ACTOR;

- (BOOL)propertyListToData:(CFMutableDataRef)data format:(GSFormatVersion)formatVersion error:(out NSError **)error;

- (NSArray *)propertyListValueFormat:(GSFormatVersion)formatVersion error:(out NSError **)error;

- (void)drawSwatchInRect:(NSRect)rect;

@end

NS_ASSUME_NONNULL_END
