Adventure Text Serializer Gson

import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
import net.kyori.adventure.text.Component;
import com.google.gson.JsonElement;

import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
import net.kyori.adventure.text.Component;

// Get standard serializer
GsonComponentSerializer serializer = GsonComponentSerializer.gson();

// Serialize component to JSON string
Component component = Component.text("Hello World");
String json = serializer.serialize(component);

// Deserialize JSON string to component
Component parsed = serializer.deserialize(json);

// Work with JsonElement directly
JsonElement jsonElement = serializer.serializeToTree(component);
Component fromTree = serializer.deserializeFromTree(jsonElement);

/**
 * Main interface for Gson-based Adventure text component serialization
 */
public interface GsonComponentSerializer extends JSONComponentSerializer, 
    Buildable<GsonComponentSerializer, GsonComponentSerializer.Builder> {
    
    /**
     * Gets a standard gson component serializer
     * @return Standard GsonComponentSerializer instance
     */
    static GsonComponentSerializer gson();
    
    /**
     * Gets a legacy gson component serializer with color downsampling
     * @return Legacy GsonComponentSerializer with color downsampling enabled
     */
    static GsonComponentSerializer colorDownsamplingGson();
    
    /**
     * Creates a new builder for custom configuration
     * @return New Builder instance
     */
    static Builder builder();
    
    /**
     * Gets the underlying gson serializer
     * @return Gson instance used for serialization
     */
    Gson serializer();
    
    /**
     * Gets the underlying gson populator
     * @return UnaryOperator that configures GsonBuilder
     */
    UnaryOperator<GsonBuilder> populator();
    
    /**
     * Deserialize a component from a JsonElement
     * @param input JsonElement to deserialize
     * @return Deserialized Component
     */
    Component deserializeFromTree(JsonElement input);
    
    /**
     * Serialize a component to a JsonElement
     * @param component Component to serialize
     * @return Serialized JsonElement
     */
    JsonElement serializeToTree(Component component);
}

// Standard serialization
GsonComponentSerializer serializer = GsonComponentSerializer.gson();
String json = serializer.serialize(component);

// Legacy compatibility (downsamples hex colors to named colors)
GsonComponentSerializer legacySerializer = GsonComponentSerializer.colorDownsamplingGson();
String legacyJson = legacySerializer.serialize(component);

// JsonElement integration
JsonElement element = serializer.serializeToTree(component);
Component restored = serializer.deserializeFromTree(element);

/**
 * Builder interface for configuring GsonComponentSerializer instances
 */
public interface Builder extends AbstractBuilder<GsonComponentSerializer>, 
    Buildable.Builder<GsonComponentSerializer>, JSONComponentSerializer.Builder {
    
    /**
     * Sets serialization options
     * @param flags OptionState containing serialization options
     * @return This builder for chaining
     */
    Builder options(OptionState flags);
    
    /**
     * Edit options using a consumer
     * @param optionEditor Consumer to edit options
     * @return This builder for chaining
     */
    Builder editOptions(Consumer<OptionState.Builder> optionEditor);
    
    /**
     * Enables downsampling of hex colors to named colors for legacy compatibility
     * @return This builder for chaining
     */
    Builder downsampleColors();
    
    /**
     * Sets legacy hover event serializer (deprecated)
     * @param serializer Legacy hover event serializer
     * @return This builder for chaining
     * @deprecated Use the non-deprecated version
     */
    @Deprecated
    Builder legacyHoverEventSerializer(LegacyHoverEventSerializer serializer);
    
    /**
     * Sets legacy hover event serializer
     * @param serializer Legacy hover event serializer from json package
     * @return This builder for chaining
     */
    Builder legacyHoverEventSerializer(
        net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer serializer);
    
    /**
     * Enables legacy hover event emission (deprecated)
     * @return This builder for chaining
     * @deprecated Use legacyHoverEventSerializer instead
     */
    @Deprecated
    Builder emitLegacyHoverEvent();
    
    /**
     * Builds the configured serializer
     * @return Configured GsonComponentSerializer instance
     */
    GsonComponentSerializer build();
}

// Custom serializer with color downsampling
GsonComponentSerializer customSerializer = GsonComponentSerializer.builder()
    .downsampleColors()
    .build();

// Advanced configuration with options
GsonComponentSerializer advancedSerializer = GsonComponentSerializer.builder()
    .editOptions(options -> options
        .emitLegacyHoverEvent(true)
        .downsampleColors(true))
    .build();

/**
 * DataComponentValue implementation that holds a JsonElement for item data
 */
@ApiStatus.NonExtendable
public interface GsonDataComponentValue extends DataComponentValue {
    
    /**
     * Creates a data component value from a JsonElement
     * @param data JsonElement containing the data
     * @return GsonDataComponentValue wrapping the JsonElement
     */
    static GsonDataComponentValue gsonDataComponentValue(JsonElement data);
    
    /**
     * Gets the contained JsonElement
     * @return JsonElement containing the component data
     */
    JsonElement element();
}

// Create data component value from JsonElement
JsonElement itemData = new JsonObject();
itemData.addProperty("custom_name", "My Item");
GsonDataComponentValue dataValue = GsonDataComponentValue.gsonDataComponentValue(itemData);

// Extract JsonElement from data component value
JsonElement extracted = dataValue.element();

/**
 * Legacy hover event serializer interface (deprecated)
 */
@Deprecated
@ApiStatus.ScheduledForRemoval(inVersion = "5.0.0")
public interface LegacyHoverEventSerializer 
    extends net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer {
    // Empty interface extending base functionality
}

/**
 * Service provider interface for GsonComponentSerializer (internal)
 */
@ApiStatus.Internal
@PlatformAPI
public interface Provider {
    GsonComponentSerializer gson();
    GsonComponentSerializer gsonLegacy();
    Consumer<Builder> builder();
}