Text Formatting and Styling

/**
 * Complete text formatting combining color, decorations, and events
 */
interface Style extends StyleGetter, StyleSetter<Style>, StyleBuilderApplicable, Buildable<Style, Style.Builder>, Examinable {
    // Style properties
    /**
     * Gets the text color
     * @return the color or null if not set
     */
    @Nullable TextColor color();
    
    /**
     * Gets the state of a text decoration
     * @param decoration the decoration to check
     * @return the decoration state
     */
    TextDecoration.State decoration(TextDecoration decoration);
    
    /**
     * Gets all decoration states
     * @return map of decorations to their states
     */
    Map<TextDecoration, TextDecoration.State> decorations();
    
    /**
     * Gets the click event
     * @return the click event or null
     */
    @Nullable ClickEvent clickEvent();
    
    /**
     * Gets the hover event
     * @return the hover event or null
     */
    @Nullable HoverEvent<?> hoverEvent();
    
    /**
     * Gets the insertion text
     * @return the insertion text or null
     */
    @Nullable String insertion();
    
    /**
     * Gets the font key
     * @return the font key or null
     */
    @Nullable Key font();
    
    
    // Style creation and modification
    /**
     * Sets the text color
     * @param color the color
     * @return new style with color
     */
    Style color(@Nullable TextColor color);
    
    /**
     * Sets a decoration state
     * @param decoration the decoration
     * @param state the state
     * @return new style with decoration
     */
    Style decoration(TextDecoration decoration, TextDecoration.State state);
    
    /**
     * Sets decoration to true state
     * @param decoration the decoration
     * @return new style with decoration enabled
     */
    Style decorate(TextDecoration decoration);
    
    /**
     * Sets multiple decorations to true state
     * @param decorations the decorations
     * @return new style with decorations enabled
     */
    Style decorate(TextDecoration... decorations);
    
    /**
     * Sets decoration to false state
     * @param decoration the decoration
     * @return new style with decoration disabled
     */
    Style undecorate(TextDecoration decoration);
    
    /**
     * Sets the click event
     * @param event the click event
     * @return new style with click event
     */
    Style clickEvent(@Nullable ClickEvent event);
    
    /**
     * Sets the hover event
     * @param event the hover event
     * @return new style with hover event
     */
    Style hoverEvent(@Nullable HoverEvent<?> event);
    
    /**
     * Sets the insertion text
     * @param insertion the insertion text
     * @return new style with insertion
     */
    Style insertion(@Nullable String insertion);
    
    /**
     * Sets the font
     * @param font the font key
     * @return new style with font
     */
    Style font(@Nullable Key font);
    
    
    /**
     * Merges this style with another style
     * @param that the other style
     * @return merged style
     */
    Style merge(Style that);
    
    /**
     * Merges styles with a merge strategy
     * @param that the other style
     * @param strategy the merge strategy
     * @return merged style
     */
    Style merge(Style that, Merge.Strategy strategy);
    
    /**
     * Edits this style using a consumer
     * @param consumer style editor
     * @return edited style
     */
    Style edit(Consumer<Style.Builder> consumer);
    
    /**
     * Edits this style using a consumer with merge strategy
     * @param consumer style editor
     * @param strategy merge strategy
     * @return edited style
     */
    Style edit(Consumer<Style.Builder> consumer, Merge.Strategy strategy);
    
    /**
     * Unmerges a style from this style
     * @param that the style to unmerge
     * @return style with removed properties
     */
    Style unmerge(Style that);
    
    /**
     * Checks if this style is empty (no formatting)
     * @return true if empty
     */
    boolean isEmpty();
    
    // Factory methods
    /**
     * Creates an empty style
     * @return empty style
     */
    static Style empty();
    
    /**
     * Creates a style with color
     * @param color the color
     * @return new style
     */
    static Style style(TextColor color);
    
    /**
     * Creates a style with decorations
     * @param decorations the decorations
     * @return new style
     */
    static Style style(TextDecoration... decorations);
    
    /**
     * Creates a style with color and decorations
     * @param color the color
     * @param decorations the decorations
     * @return new style
     */
    static Style style(TextColor color, TextDecoration... decorations);
    
    /**
     * Creates a style using a consumer
     * @param consumer style configuration
     * @return new style
     */
    static Style style(Consumer<Style.Builder> consumer);
    
    /**
     * Creates a style with single decoration
     * @param decoration the decoration
     * @return new style
     */
    static Style style(TextDecoration decoration);
    
    /**
     * Creates a style from iterable applicables
     * @param applicables the style applicables
     * @return new style
     */
    static Style style(Iterable<? extends StyleBuilderApplicable> applicables);
    
    /**
     * Creates a style builder
     * @return new builder
     */
    static Builder style();
    
    /**
     * Builder for creating styles
     */
    interface Builder extends AbstractBuilder<Style>, StyleSetter<Builder> {
        // Builder inherits all StyleSetter methods
    }
    
    /**
     * Style merging operations
     */
    interface Merge {
        /**
         * Merge strategy for combining styles
         */
        interface Strategy {
            /**
             * Merges two colors
             * @param first the first color
             * @param second the second color
             * @return merged color
             */
            @Nullable TextColor mergeColor(@Nullable TextColor first, @Nullable TextColor second);
            
            /**
             * Merges decoration states
             * @param first the first state
             * @param second the second state
             * @return merged state
             */
            TextDecoration.State mergeDecoration(TextDecoration.State first, TextDecoration.State second);
            
            /**
             * Merges click events
             * @param first the first event
             * @param second the second event
             * @return merged event
             */
            @Nullable ClickEvent mergeClickEvent(@Nullable ClickEvent first, @Nullable ClickEvent second);
            
            /**
             * Merges hover events
             * @param first the first event
             * @param second the second event
             * @return merged event
             */
            @Nullable HoverEvent<?> mergeHoverEvent(@Nullable HoverEvent<?> first, @Nullable HoverEvent<?> second);
            
            /**
             * Merges insertion strings
             * @param first the first insertion
             * @param second the second insertion
             * @return merged insertion
             */
            @Nullable String mergeInsertion(@Nullable String first, @Nullable String second);
            
            /**
             * Merges fonts
             * @param first the first font
             * @param second the second font
             * @return merged font
             */
            @Nullable Key mergeFont(@Nullable Key first, @Nullable Key second);
        }
    }
}

import net.kyori.adventure.text.format.Style;
import net.kyori.adventure.text.format.NamedTextColor;
import net.kyori.adventure.text.format.TextDecoration;

// Create styles
Style redBold = Style.style(NamedTextColor.RED, TextDecoration.BOLD);
Style blueItalic = Style.style(NamedTextColor.BLUE, TextDecoration.ITALIC);

// Build complex styles
Style complex = Style.style()
    .color(NamedTextColor.GREEN)
    .decorate(TextDecoration.UNDERLINED)
    .clickEvent(ClickEvent.openUrl("https://example.com"))
    .hoverEvent(HoverEvent.showText(Component.text("Click to visit website")))
    .build();

// Merge styles
Style merged = redBold.merge(blueItalic); // Blue color with both bold and italic

// Apply to components
Component styledText = Component.text("Styled text").style(complex);

/**
 * Interface for text colors with RGB values
 */
interface TextColor extends Examinable, StyleBuilderApplicable, TextFormat {
    /**
     * Gets the RGB color value
     * @return the color value as 24-bit RGB
     */
    int value();
    
    /**
     * Gets the red component (0-255)
     * @return red component
     */
    default int red() {
        return (this.value() >> 16) & 0xFF;
    }
    
    /**
     * Gets the green component (0-255)
     * @return green component
     */
    default int green() {
        return (this.value() >> 8) & 0xFF;
    }
    
    /**
     * Gets the blue component (0-255)
     * @return blue component
     */
    default int blue() {
        return this.value() & 0xFF;
    }
    
    /**
     * Creates a text color from RGB value
     * @param value the RGB value
     * @return new text color
     */
    static TextColor color(int value);
    
    /**
     * Creates a text color from RGB components
     * @param r red component (0-255)
     * @param g green component (0-255)
     * @param b blue component (0-255)
     * @return new text color
     */
    static TextColor color(int r, int g, int b);
    
    /**
     * Creates a text color from RGB object
     * @param rgb the RGB object
     * @return new text color
     */
    static TextColor color(RGBLike rgb);
    
    /**
     * Creates a color from RGB components (0.0-1.0)
     * @param r red component
     * @param g green component  
     * @param b blue component
     * @return new text color
     */
    static TextColor color(float r, float g, float b);
    
    /**
     * Creates a color from HSV color space
     * @param hsv HSV color representation
     * @return new text color
     */
    static TextColor color(HSVLike hsv);
    
    /**
     * Creates a text color from hex string
     * @param string the hex string (e.g., "#ff0000" or "ff0000")
     * @return new text color
     */
    static TextColor fromHexString(String string);
    
    /**
     * Creates a text color from CSS hex string
     * @param hex the CSS hex string
     * @return new text color or null if invalid
     */
    static @Nullable TextColor fromCSSHexString(String hex);
    
    /**
     * Converts to hex string representation
     * @return hex string (e.g., "#ff0000")
     */
    String asHexString();
    
    /**
     * Linearly interpolates between two colors
     * @param t interpolation factor (0.0 to 1.0)
     * @param a the first color
     * @param b the second color
     * @return interpolated color
     */
    static TextColor lerp(float t, RGBLike a, RGBLike b);
}

/**
 * Standard Minecraft named colors
 */
enum NamedTextColor implements TextColor {
    BLACK(0x000000),
    DARK_BLUE(0x0000aa),
    DARK_GREEN(0x00aa00),
    DARK_AQUA(0x00aaaa),
    DARK_RED(0xaa0000),
    DARK_PURPLE(0xaa00aa),
    GOLD(0xffaa00),
    GRAY(0xaaaaaa),
    DARK_GRAY(0x555555),
    BLUE(0x5555ff),
    GREEN(0x55ff55),
    AQUA(0x55ffff),
    RED(0xff5555),
    LIGHT_PURPLE(0xff55ff),
    YELLOW(0xffff55),
    WHITE(0xffffff);
    
    /**
     * Gets a named color by name
     * @param name the color name
     * @return the named color or null
     */
    static @Nullable NamedTextColor namedColor(String name);
    
    /**
     * Gets the nearest named color to an RGB value
     * @param color the color to match
     * @return nearest named color
     */
    static NamedTextColor nearestTo(TextColor color);
    
    /**
     * Gets all named color values
     * @return array of all named colors
     */
    static NamedTextColor[] values();
}

/**
 * Text decorations for styling text
 */
enum TextDecoration implements StyleBuilderApplicable, TextFormat {
    /**
     * Obfuscated/magic text that changes randomly
     */
    OBFUSCATED("obfuscated"),
    
    /**
     * Bold text
     */
    BOLD("bold"),
    
    /**
     * Strikethrough text
     */
    STRIKETHROUGH("strikethrough"),
    
    /**
     * Underlined text
     */
    UNDERLINED("underlined"),
    
    /**
     * Italic text
     */
    ITALIC("italic");
    
    /**
     * Gets the decoration by name
     * @param name the decoration name
     * @return the decoration or null
     */
    static @Nullable TextDecoration byName(String name);
    
    /**
     * Gets all decoration values
     * @return set of all decorations
     */
    static Set<TextDecoration> values();
    
    /**
     * State of a text decoration
     */
    enum State {
        /**
         * Decoration state is not set (inherit from parent)
         */
        NOT_SET,
        
        /**
         * Decoration is explicitly disabled
         */
        FALSE,
        
        /**
         * Decoration is explicitly enabled
         */
        TRUE;
        
        /**
         * Gets state by boolean value
         * @param flag the boolean value
         * @return TRUE if true, FALSE if false
         */
        static State byBoolean(boolean flag);
        
        /**
         * Gets state by boolean, with NOT_SET for null
         * @param flag the boolean value or null
         * @return appropriate state
         */
        static State byBoolean(@Nullable Boolean flag);
    }
}

/**
 * Text decoration combined with its state
 */
interface TextDecorationAndState extends Examinable {
    /**
     * Gets the decoration
     * @return the decoration
     */
    TextDecoration decoration();
    
    /**
     * Gets the state
     * @return the state
     */
    TextDecoration.State state();
    
    /**
     * Creates a decoration and state combination
     * @param decoration the decoration
     * @param state the state
     * @return new decoration and state
     */
    static TextDecorationAndState of(TextDecoration decoration, TextDecoration.State state);
    
    /**
     * Creates decoration with TRUE state
     * @param decoration the decoration
     * @return decoration with TRUE state
     */
    static TextDecorationAndState of(TextDecoration decoration);
}

/**
 * Interface for objects that have style information
 */
interface StyleGetter {
    /**
     * Gets the style
     * @return the style
     */
    Style style();
    
    /**
     * Gets the text color
     * @return the color or null
     */
    default @Nullable TextColor color() {
        return this.style().color();
    }
    
    /**
     * Gets a decoration state
     * @param decoration the decoration
     * @return the decoration state
     */
    default TextDecoration.State decoration(TextDecoration decoration) {
        return this.style().decoration(decoration);
    }
    
    /**
     * Checks if a decoration is present and enabled
     * @param decoration the decoration
     * @return true if decoration is TRUE
     */
    default boolean hasDecoration(TextDecoration decoration) {
        return this.decoration(decoration) == TextDecoration.State.TRUE;
    }
    
    /**
     * Gets the click event
     * @return the click event or null
     */
    default @Nullable ClickEvent clickEvent() {
        return this.style().clickEvent();
    }
    
    /**
     * Gets the hover event
     * @return the hover event or null
     */
    default @Nullable HoverEvent<?> hoverEvent() {
        return this.style().hoverEvent();
    }
    
    /**
     * Gets the insertion text
     * @return the insertion text or null
     */
    default @Nullable String insertion() {
        return this.style().insertion();
    }
    
    /**
     * Gets the font
     * @return the font key or null
     */
    default @Nullable Key font() {
        return this.style().font();
    }
}

/**
 * Interface for objects that can have style applied
 */
interface StyleSetter<T> {
    /**
     * Sets the style
     * @param style the style
     * @return object with new style
     */
    T style(Style style);
    
    /**
     * Applies a style configurator
     * @param applicableStyle the style to apply
     * @return object with applied style
     */
    T style(StyleBuilderApplicable applicableStyle);
    
    /**
     * Applies multiple style configurators
     * @param applicableStyles the styles to apply
     * @return object with applied styles
     */
    T style(StyleBuilderApplicable... applicableStyles);
    
    /**
     * Merges with another style
     * @param style the style to merge
     * @return object with merged style
     */
    T mergeStyle(Style style);
    
    /**
     * Merges with another style using a merge strategy
     * @param style the style to merge
     * @param strategy the merge strategy
     * @return object with merged style
     */
    T mergeStyle(Style style, Style.Merge.Strategy strategy);
    
    /**
     * Sets the text color
     * @param color the color
     * @return object with new color
     */
    T color(@Nullable TextColor color);
    
    /**
     * Sets the text color using RGB
     * @param color the RGB color
     * @return object with new color
     */
    T color(@Nullable RGBLike color);
    
    /**
     * Removes the text color
     * @return object without color
     */
    default T colorIfAbsent(@Nullable TextColor color) {
        return this.color() == null ? this.color(color) : (T) this;
    }
    
    /**
     * Sets a decoration state
     * @param decoration the decoration
     * @param state the state
     * @return object with decoration state
     */
    T decoration(TextDecoration decoration, TextDecoration.State state);
    
    /**
     * Sets a decoration state by boolean
     * @param decoration the decoration
     * @param flag the boolean state
     * @return object with decoration state
     */
    T decoration(TextDecoration decoration, boolean flag);
    
    /**
     * Enables a decoration
     * @param decoration the decoration
     * @return object with decoration enabled
     */
    default T decorate(TextDecoration decoration) {
        return this.decoration(decoration, TextDecoration.State.TRUE);
    }
    
    /**
     * Enables multiple decorations
     * @param decorations the decorations
     * @return object with decorations enabled
     */
    T decorate(TextDecoration... decorations);
    
    /**
     * Disables a decoration
     * @param decoration the decoration
     * @return object with decoration disabled
     */
    default T undecorate(TextDecoration decoration) {
        return this.decoration(decoration, TextDecoration.State.FALSE);
    }
    
    /**
     * Disables multiple decorations
     * @param decorations the decorations
     * @return object with decorations disabled
     */
    T undecorate(TextDecoration... decorations);
    
    /**
     * Sets the click event
     * @param event the click event
     * @return object with click event
     */
    T clickEvent(@Nullable ClickEvent event);
    
    /**
     * Sets the hover event
     * @param event the hover event
     * @return object with hover event
     */
    T hoverEvent(@Nullable HoverEvent<?> event);
    
    /**
     * Sets the insertion text
     * @param insertion the insertion text
     * @return object with insertion
     */
    T insertion(@Nullable String insertion);
    
    /**
     * Sets the font
     * @param font the font key
     * @return object with font
     */
    T font(@Nullable Key font);
}

/**
 * Style setter that modifies the object in place
 */
interface MutableStyleSetter<T> extends StyleSetter<T> {
    // Inherits all StyleSetter methods but implementations modify in place
}

/**
 * Objects that can be applied to style builders
 */
interface StyleBuilderApplicable {
    /**
     * Applies this object to a style builder
     * @param builder the style builder
     */
    void styleApply(Style.Builder builder);
}

/**
 * Base interface for text formatting elements
 */
interface TextFormat extends Examinable {
    // Marker interface - implementations provide specific formatting behavior
}

/**
 * Interface for objects with RGB color values
 */
interface RGBLike {
    /**
     * Gets the red component (0-255)
     * @return red component
     */
    int red();
    
    /**
     * Gets the green component (0-255)
     * @return green component
     */
    int green();
    
    /**
     * Gets the blue component (0-255)
     * @return blue component
     */
    int blue();
}

/**
 * Interface for objects with ARGB color values
 */
interface ARGBLike extends RGBLike {
    /**
     * Gets the alpha component (0-255)
     * @return alpha component
     */
    int alpha();
    
    /**
     * Gets the ARGB value as a 32-bit integer
     * @return ARGB value
     */
    default int argb() {
        return (this.alpha() << 24) | (this.red() << 16) | (this.green() << 8) | this.blue();
    }
}

/**
 * Interface for objects with HSV color values
 */
interface HSVLike {
    /**
     * Gets the hue component (0.0-360.0)
     * @return hue in degrees
     */
    float h();
    
    /**
     * Gets the saturation component (0.0-1.0)
     * @return saturation
     */
    float s();
    
    /**
     * Gets the value/brightness component (0.0-1.0)
     * @return value
     */
    float v();
}

// Using named colors
TextColor red = NamedTextColor.RED;
TextColor blue = NamedTextColor.BLUE;

// Using hex colors
TextColor purple = TextColor.fromHexString("#800080");
TextColor orange = TextColor.color(255, 165, 0);

// Color interpolation
TextColor gradient = TextColor.lerp(0.5f, red, blue); // 50% between red and blue

// Building complex styles
Style errorStyle = Style.style()
    .color(NamedTextColor.RED)
    .decorate(TextDecoration.BOLD)
    .hoverEvent(HoverEvent.showText(Component.text("Error details here")))
    .build();

// Reusable style components
Style linkStyle = Style.style(NamedTextColor.BLUE, TextDecoration.UNDERLINED);
Style importantStyle = Style.style(NamedTextColor.YELLOW, TextDecoration.BOLD);

// Style merging
Style combinedStyle = linkStyle.merge(importantStyle);

// Apply styling based on conditions
Component message = Component.text(content)
    .color(isError ? NamedTextColor.RED : NamedTextColor.GREEN)
    .decorateIf(isImportant, TextDecoration.BOLD);

// Style inheritance patterns
Style baseStyle = Style.style(NamedTextColor.WHITE);
Style warningStyle = baseStyle.color(NamedTextColor.YELLOW);
Style errorStyle = baseStyle.color(NamedTextColor.RED).decorate(TextDecoration.BOLD);