Text Components

/**
 * Root interface for all text components - immutable text with styling and events
 */
interface Component extends ComponentLike, Examinable, HoverEventSource<Component>, StyleGetter, StyleSetter<Component> {
    // Factory methods for creating components
    static Component empty();
    static Component newline();
    static Component space();
    static TextComponent text(String content);
    static TextComponent text(String content, TextColor color);
    static TextComponent text(String content, TextColor color, TextDecoration... decorations);
    static TranslatableComponent translatable(String key);
    static TranslatableComponent translatable(String key, ComponentLike... arguments);
    static KeybindComponent keybind(String keybind);
    static ScoreComponent score(String name, String objective);
    static SelectorComponent selector(String pattern);
    static BlockNBTComponent blockNBT(String nbtPath, BlockNBTComponent.Pos pos);
    static EntityNBTComponent entityNBT(String nbtPath, String selector);
    static StorageNBTComponent storageNBT(String nbtPath, Key storage);
    
    // Component joining and composition
    static Component join(ComponentLike separator, ComponentLike... components);
    static Component join(ComponentLike separator, Iterable<? extends ComponentLike> components);
    static Component join(JoinConfiguration configuration, ComponentLike... components);
    static Component join(JoinConfiguration configuration, Iterable<? extends ComponentLike> components);
    
    // Component properties and manipulation
    List<Component> children();
    Component children(List<? extends ComponentLike> children);
    boolean hasStyling();
    Component append(Component component);
    Component append(ComponentLike component);
    Component appendSpace();
    Component appendNewline();
    
    // Text replacement and processing
    Component replaceText(TextReplacementConfig config);
    Component replaceText(Pattern pattern, ComponentLike replacement);
    Component replaceText(String search, ComponentLike replacement);
    
    // Component iteration and inspection
    Iterable<Component> iterable(ComponentIteratorType type, ComponentIteratorFlag... flags);
    void detectUrls(UrlConsumer action);
    
    // Compact representation
    Component compact();
}

/**
 * Component with plain string content
 */
interface TextComponent extends BuildableComponent<TextComponent, TextComponent.Builder> {
    /**
     * Gets the plain text content
     * @return the text content
     */
    String content();
    
    /**
     * Sets the text content
     * @param content the new content
     * @return component with new content
     */
    TextComponent content(String content);
    
    /**
     * Builder for creating text components
     */
    interface Builder extends ComponentBuilder<TextComponent, Builder> {
        /**
         * Sets the text content
         * @param content the content
         * @return this builder
         */
        Builder content(String content);
    }
}

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

// Simple text
Component simple = Component.text("Hello World!");

// Text with color
Component colored = Component.text("Red text", NamedTextColor.RED);

// Text with multiple decorations
Component decorated = Component.text("Bold italic text", NamedTextColor.BLUE, TextDecoration.BOLD, TextDecoration.ITALIC);

// Using builder pattern
Component complex = Component.text()
    .content("Complex text")
    .color(NamedTextColor.GREEN)
    .decorate(TextDecoration.UNDERLINED)
    .append(Component.space())
    .append(Component.text("with more", NamedTextColor.YELLOW))
    .build();

/**
 * Component that displays translated text
 */
interface TranslatableComponent extends BuildableComponent<TranslatableComponent, TranslatableComponent.Builder> {
    /**
     * Gets the translation key
     * @return the translation key
     */
    String key();
    
    /**
     * Sets the translation key
     * @param key the translation key
     * @return component with new key
     */
    TranslatableComponent key(String key);
    
    /**
     * Gets the translation arguments
     * @return list of translation arguments
     */
    List<TranslationArgument> arguments();
    
    /**
     * Sets the translation arguments
     * @param arguments the arguments
     * @return component with new arguments
     */
    TranslatableComponent arguments(List<? extends TranslationArgumentLike> arguments);
    TranslatableComponent arguments(TranslationArgumentLike... arguments);
    
    /**
     * Gets the fallback string used when translation is not available
     * @return the fallback string or null
     */
    @Nullable String fallback();
    
    /**
     * Sets the fallback string
     * @param fallback the fallback string
     * @return component with new fallback
     */
    TranslatableComponent fallback(@Nullable String fallback);
    
    interface Builder extends ComponentBuilder<TranslatableComponent, Builder> {
        Builder key(String key);
        Builder arguments(List<? extends TranslationArgumentLike> arguments);
        Builder arguments(TranslationArgumentLike... arguments);
        Builder fallback(@Nullable String fallback);
    }
}

// Basic translation
Component welcome = Component.translatable("welcome.message");

// Translation with arguments
Component playerJoined = Component.translatable("player.joined", 
    Component.text("PlayerName", NamedTextColor.YELLOW));

// Translation with fallback
Component withFallback = Component.translatable()
    .key("custom.message")
    .fallback("Default message")
    .arguments(Component.text("arg1"))
    .build();

/**
 * Component displaying a keybind name
 */
interface KeybindComponent extends BuildableComponent<KeybindComponent, KeybindComponent.Builder> {
    /**
     * Gets the keybind identifier
     * @return the keybind string
     */
    String keybind();
    
    /**
     * Sets the keybind identifier
     * @param keybind the keybind string
     * @return component with new keybind
     */
    KeybindComponent keybind(String keybind);
    
    interface Builder extends ComponentBuilder<KeybindComponent, Builder> {
        Builder keybind(String keybind);
    }
}

// Show jump key
Component jumpKey = Component.keybind("key.jump");

// Show attack key in context
Component instruction = Component.text("Press ")
    .append(Component.keybind("key.attack").color(NamedTextColor.YELLOW))
    .append(Component.text(" to attack"));

/**
 * Component displaying a scoreboard value
 */
interface ScoreComponent extends BuildableComponent<ScoreComponent, ScoreComponent.Builder> {
    /**
     * Gets the score holder name (player name, selector, etc.)
     * @return the name
     */
    String name();
    
    /**
     * Sets the score holder name
     * @param name the name
     * @return component with new name
     */
    ScoreComponent name(String name);
    
    /**
     * Gets the objective name
     * @return the objective
     */
    String objective();
    
    /**
     * Sets the objective name
     * @param objective the objective
     * @return component with new objective
     */
    ScoreComponent objective(String objective);
    
    /**
     * Gets the optional fixed value override
     * @return the value or null
     */
    @Nullable String value();
    
    /**
     * Sets a fixed value override
     * @param value the value or null to use scoreboard
     * @return component with new value
     */
    ScoreComponent value(@Nullable String value);
    
    interface Builder extends ComponentBuilder<ScoreComponent, Builder> {
        Builder name(String name);
        Builder objective(String objective);
        Builder value(@Nullable String value);
    }
}

/**
 * Component using entity selector patterns
 */
interface SelectorComponent extends BuildableComponent<SelectorComponent, SelectorComponent.Builder> {
    /**
     * Gets the selector pattern
     * @return the selector string
     */
    String pattern();
    
    /**
     * Sets the selector pattern
     * @param pattern the selector
     * @return component with new pattern
     */
    SelectorComponent pattern(String pattern);
    
    /**
     * Gets the separator used between multiple results
     * @return the separator component or null
     */
    @Nullable Component separator();
    
    /**
     * Sets the separator for multiple results  
     * @param separator the separator or null
     * @return component with new separator
     */
    SelectorComponent separator(@Nullable ComponentLike separator);
    
    interface Builder extends ComponentBuilder<SelectorComponent, Builder> {
        Builder pattern(String pattern);
        Builder separator(@Nullable ComponentLike separator);
    }
}

/**
 * Base interface for component builders
 */
interface ComponentBuilder<C extends Component, B extends ComponentBuilder<C, B>> 
    extends AbstractBuilder<C>, ComponentBuilderApplicable, StyleSetter<B> {
    
    /**
     * Appends a component to the children list
     * @param component the component to append
     * @return this builder
     */
    B append(Component component);
    B append(ComponentLike component);
    B appendSpace();
    B appendNewline();
    
    /**
     * Sets the children list
     * @param children the children components
     * @return this builder
     */
    B children(List<? extends ComponentLike> children);
    
    /**
     * Applies a style configurator
     * @param styleApplicable the style to apply
     * @return this builder
     */
    B style(StyleBuilderApplicable styleApplicable);
    
    /**
     * Builds the final component
     * @return the built component
     */
    C build();
}

/**
 * Specialized builder for NBT components
 */
interface NBTComponentBuilder<C extends NBTComponent<C, B>, B extends NBTComponentBuilder<C, B>> 
    extends ComponentBuilder<C, B> {
    
    /**
     * Sets the NBT path expression
     * @param nbtPath the path
     * @return this builder
     */
    B nbtPath(String nbtPath);
    
    /**
     * Sets whether to interpret NBT as components
     * @param interpret whether to interpret
     * @return this builder
     */
    B interpret(boolean interpret);
    
    /**
     * Sets the separator for multiple NBT results
     * @param separator the separator or null
     * @return this builder
     */
    B separator(@Nullable ComponentLike separator);
}

/**
 * Utilities for linear component operations
 */
class LinearComponents {
    /**
     * Collects components into a linear sequence
     * @return collector for components
     */
    static Collector<Component, ?, Component> toLinearComponents();
    
    /**
     * Creates a linear component from components
     * @param components the components
     * @return linear component
     */
    static Component linear(ComponentLike... components);
}

/**
 * Configuration for joining components
 */
interface JoinConfiguration extends Examinable {
    /**
     * Gets the separator used between components
     * @return the separator
     */
    ComponentLike separator();
    
    /**
     * Gets the last separator (used before final component)
     * @return the last separator or null to use normal separator
     */
    @Nullable ComponentLike lastSeparator();
    
    /**
     * Gets the separator for exactly two components
     * @return the two separator or null to use normal separator
     */
    @Nullable ComponentLike lastSeparatorIfTwo();
    
    /**
     * Gets the prefix applied to the joined result
     * @return the prefix or null
     */
    @Nullable ComponentLike prefix();
    
    /**
     * Gets the suffix applied to the joined result  
     * @return the suffix or null
     */
    @Nullable ComponentLike suffix();
    
    /**
     * Creates join configuration
     * @param separator the separator
     * @return new configuration
     */
    static JoinConfiguration separator(ComponentLike separator);
    
    /**
     * Creates builder for join configuration
     * @return new builder
     */
    static Builder builder();
    
    interface Builder extends AbstractBuilder<JoinConfiguration> {
        Builder separator(ComponentLike separator);
        Builder lastSeparator(@Nullable ComponentLike lastSeparator);
        Builder lastSeparatorIfTwo(@Nullable ComponentLike lastSeparatorIfTwo);
        Builder prefix(@Nullable ComponentLike prefix);
        Builder suffix(@Nullable ComponentLike suffix);
    }
}

/**
 * Objects that can be converted to components
 */
interface ComponentLike {
    /**
     * Converts this object to a component
     * @return the component representation
     */
    Component asComponent();
}

/**
 * Objects that can be applied to components
 */
interface ComponentApplicable {
    /**
     * Applies this object to a component
     * @param component the target component
     * @return the modified component
     */
    Component componentApply(Component component);
}

/**
 * Objects that can be applied to component builders
 */
interface ComponentBuilderApplicable {
    /**
     * Applies this object to a component builder
     * @param builder the target builder
     */
    <B extends ComponentBuilder<?, B>> void componentBuilderApply(B builder);
}

/**
 * Base interface for buildable components
 */
interface BuildableComponent<C extends BuildableComponent<C, B>, B extends ComponentBuilder<C, B>> 
    extends Component {
    
    /**
     * Creates a builder pre-populated with this component's values
     * @return new builder
     */
    B toBuilder();
}

/**
 * Base builder interface
 */
interface AbstractBuilder<R> {
    /**
     * Builds the final result
     * @return the built object
     */
    R build();
}

/**
 * Types of component iteration
 */
interface ComponentIteratorType {
    ComponentIteratorType DEPTH_FIRST = ComponentIteratorType.create("depth_first");
    ComponentIteratorType BREADTH_FIRST = ComponentIteratorType.create("breadth_first");
    
    static ComponentIteratorType create(String name);
}

/**
 * Flags for component iteration behavior
 */
enum ComponentIteratorFlag {
    /**
     * Include the root component in iteration
     */
    INCLUDE_TRANSLATABLE_COMPONENT_ARGUMENTS
}

/**
 * Consumer for URL detection in components
 */
interface UrlConsumer {
    /**
     * Called when a URL is detected
     * @param url the detected URL
     */
    void accept(String url);
}