Events and Interactivity

/**
 * Click event that executes an action when text is clicked
 */
class ClickEvent implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
    /**
     * Gets the click action type
     * @return the action
     */
    Action action();
    
    /**
     * Gets the click action value/parameter
     * @return the value string
     */
    String value();
    
    // Factory methods for common click actions
    /**
     * Opens a URL in the client's browser
     * @param url the URL to open
     * @return click event for opening URL
     */
    static ClickEvent openUrl(String url);
    
    /**
     * Opens a URL with validation
     * @param url the URL to open
     * @return click event for opening URL
     */
    static ClickEvent openUrl(URL url);
    
    /**
     * Opens a file (client-side only)
     * @param file the file path to open
     * @return click event for opening file
     */
    static ClickEvent openFile(String file);
    
    /**
     * Runs a command as the clicking player
     * @param command the command to run (without /)
     * @return click event for running command
     */
    static ClickEvent runCommand(String command);
    
    /**
     * Suggests a command in the player's chat input
     * @param command the command to suggest
     * @return click event for suggesting command
     */
    static ClickEvent suggestCommand(String command);
    
    /**
     * Changes the page in a book
     * @param page the page number to go to
     * @return click event for changing page
     */
    static ClickEvent changePage(String page);
    
    /**
     * Changes the page in a book
     * @param page the page number to go to
     * @return click event for changing page
     */
    static ClickEvent changePage(int page);
    
    /**
     * Copies text to the client's clipboard
     * @param text the text to copy
     * @return click event for copying to clipboard
     */
    static ClickEvent copyToClipboard(String text);
    
    /**
     * Executes a callback function (server-side)
     * @param function the callback function
     * @return click event for callback
     */
    static ClickEvent callback(ClickCallback<Audience> function);
    
    /**
     * Creates a click event
     * @param action the action type
     * @param value the action value
     * @return new click event
     */
    static ClickEvent clickEvent(Action action, String value);
    
    /**
     * Types of click actions
     */
    enum Action {
        /**
         * Opens a URL in browser
         */
        OPEN_URL("open_url"),
        
        /**
         * Opens a file (client-side)
         */
        OPEN_FILE("open_file"),
        
        /**
         * Runs a command as the player
         */
        RUN_COMMAND("run_command"),
        
        /**
         * Suggests command in chat input
         */
        SUGGEST_COMMAND("suggest_command"),
        
        /**
         * Changes book page
         */
        CHANGE_PAGE("change_page"),
        
        /**
         * Copies text to clipboard
         */
        COPY_TO_CLIPBOARD("copy_to_clipboard"),
        
        /**
         * Executes server-side callback
         */
        CALLBACK("callback");
        
        /**
         * Checks if this action is readable by the client
         * @return true if client can handle this action
         */
        boolean readable();
    }
}

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.event.ClickEvent;
import net.kyori.adventure.text.format.NamedTextColor;

// URL link
Component link = Component.text("Visit our website")
    .color(NamedTextColor.BLUE)
    .clickEvent(ClickEvent.openUrl("https://example.com"));

// Command execution
Component teleportHome = Component.text("[Home]")
    .color(NamedTextColor.GREEN)
    .clickEvent(ClickEvent.runCommand("/home"));

// Command suggestion
Component helpCommand = Component.text("Need help?")
    .clickEvent(ClickEvent.suggestCommand("/help "));

// Copy to clipboard
Component copyCode = Component.text("Copy Code")
    .clickEvent(ClickEvent.copyToClipboard("print('Hello World')"));

// Server-side callback
Component callbackButton = Component.text("Click me!")
    .clickEvent(ClickEvent.callback(audience -> {
        audience.sendMessage(Component.text("Button clicked!"));
    }));

/**
 * Callback interface for handling click events
 */
interface ClickCallback<T> {
    /**
     * Called when the click event is triggered
     * @param context the context object (usually Audience)
     */
    void accept(T context);
    
    /**
     * Creates a simple callback
     * @param callback the callback function
     * @return new click callback
     */
    static <T> ClickCallback<T> of(Consumer<T> callback);
}

/**
 * Hover event that displays content when text is hovered
 */
class HoverEvent<V> implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
    /**
     * Gets the hover action type
     * @return the action
     */
    Action<V> action();
    
    /**
     * Gets the hover content value
     * @return the hover content
     */
    V value();
    
    // Factory methods for common hover types
    /**
     * Shows text when hovered
     * @param text the text to show
     * @return hover event for showing text
     */
    static HoverEvent<Component> showText(ComponentLike text);
    
    /**
     * Shows item information when hovered
     * @param item the item to show
     * @return hover event for showing item
     */
    static HoverEvent<ShowItem> showItem(ShowItem item);
    
    /**
     * Shows item information from key and count
     * @param item the item key
     * @param count the item count
     * @return hover event for showing item
     */
    static HoverEvent<ShowItem> showItem(Key item, int count);
    
    /**
     * Shows entity information when hovered
     * @param entity the entity to show
     * @return hover event for showing entity
     */
    static HoverEvent<ShowEntity> showEntity(ShowEntity entity);
    
    /**
     * Shows entity information from type and UUID
     * @param type the entity type
     * @param id the entity UUID
     * @return hover event for showing entity
     */
    static HoverEvent<ShowEntity> showEntity(Key type, UUID id);
    
    /**
     * Shows entity with custom name
     * @param type the entity type
     * @param id the entity UUID
     * @param name the entity name
     * @return hover event for showing entity
     */
    static HoverEvent<ShowEntity> showEntity(Key type, UUID id, ComponentLike name);
    
    /**
     * Creates a hover event
     * @param action the action type
     * @param value the hover content
     * @return new hover event
     */
    static <V> HoverEvent<V> hoverEvent(Action<V> action, V value);
    
    /**
     * Types of hover actions
     */
    interface Action<V> extends Examinable {
        Action<Component> SHOW_TEXT = Action.of("show_text", Component.class);
        Action<ShowItem> SHOW_ITEM = Action.of("show_item", ShowItem.class);
        Action<ShowEntity> SHOW_ENTITY = Action.of("show_entity", ShowEntity.class);
        
        /**
         * Gets the action type class
         * @return the value type
         */
        Class<V> type();
        
        /**
         * Checks if this action is readable by the client
         * @return true if client can handle this action
         */
        boolean readable();
        
        /**
         * Creates an action
         * @param name the action name
         * @param type the value type
         * @return new action
         */
        static <V> Action<V> of(String name, Class<V> type);
    }
    
    /**
     * Item information for hover events
     */
    interface ShowItem extends Examinable {
        /**
         * Gets the item type key
         * @return the item type
         */
        Key item();
        
        /**
         * Gets the item count
         * @return the count
         */
        int count();
        
        /**
         * Gets the item NBT data
         * @return the NBT data or null
         */
        @Nullable BinaryTagHolder nbt();
        
        /**
         * Sets the item type
         * @param item the item type
         * @return new show item with type
         */
        ShowItem item(Key item);
        
        /**
         * Sets the item count
         * @param count the count
         * @return new show item with count
         */
        ShowItem count(int count);
        
        /**
         * Sets the item NBT data
         * @param nbt the NBT data
         * @return new show item with NBT
         */
        ShowItem nbt(@Nullable BinaryTagHolder nbt);
        
        /**
         * Creates show item data
         * @param item the item type
         * @param count the count
         * @return new show item
         */
        static ShowItem showItem(Key item, int count);
        
        /**
         * Creates show item data with NBT
         * @param item the item type
         * @param count the count
         * @param nbt the NBT data
         * @return new show item
         */
        static ShowItem showItem(Key item, int count, @Nullable BinaryTagHolder nbt);
        
        /**
         * Creates builder for show item
         * @return new builder
         */
        static Builder builder();
        
        interface Builder extends AbstractBuilder<ShowItem> {
            Builder item(Key item);
            Builder count(int count);
            Builder nbt(@Nullable BinaryTagHolder nbt);
        }
    }
    
    /**
     * Entity information for hover events
     */
    interface ShowEntity extends Examinable {
        /**
         * Gets the entity type key
         * @return the entity type
         */
        Key type();
        
        /**
         * Gets the entity UUID
         * @return the UUID
         */
        UUID id();
        
        /**
         * Gets the entity name
         * @return the name or null
         */
        @Nullable Component name();
        
        /**
         * Sets the entity type
         * @param type the entity type
         * @return new show entity with type
         */
        ShowEntity type(Key type);
        
        /**
         * Sets the entity UUID
         * @param id the UUID
         * @return new show entity with UUID
         */
        ShowEntity id(UUID id);
        
        /**
         * Sets the entity name
         * @param name the name
         * @return new show entity with name
         */
        ShowEntity name(@Nullable ComponentLike name);
        
        /**
         * Creates show entity data
         * @param type the entity type
         * @param id the UUID
         * @return new show entity
         */
        static ShowEntity showEntity(Key type, UUID id);
        
        /**
         * Creates show entity data with name
         * @param type the entity type
         * @param id the UUID
         * @param name the name
         * @return new show entity
         */
        static ShowEntity showEntity(Key type, UUID id, @Nullable ComponentLike name);
        
        /**
         * Creates builder for show entity
         * @return new builder
         */
        static Builder builder();
        
        interface Builder extends AbstractBuilder<ShowEntity> {
            Builder type(Key type);
            Builder id(UUID id);
            Builder name(@Nullable ComponentLike name);
        }
    }
}

import net.kyori.adventure.text.event.HoverEvent;
import net.kyori.adventure.key.Key;
import java.util.UUID;

// Text tooltip
Component tooltip = Component.text("Hover me")
    .hoverEvent(HoverEvent.showText(
        Component.text("This appears when you hover!", NamedTextColor.YELLOW)
    ));

// Complex tooltip with formatting
Component complexTooltip = Component.text("Information")
    .hoverEvent(HoverEvent.showText(
        Component.text()
            .append(Component.text("Server: ", NamedTextColor.GRAY))
            .append(Component.text("Example Server", NamedTextColor.WHITE))
            .appendNewline()
            .append(Component.text("Players: ", NamedTextColor.GRAY))
            .append(Component.text("24/100", NamedTextColor.GREEN))
            .build()
    ));

// Item tooltip
Component itemDisplay = Component.text("Diamond Sword")
    .hoverEvent(HoverEvent.showItem(Key.key("minecraft:diamond_sword"), 1));

// Entity tooltip
Component playerName = Component.text("Steve")
    .hoverEvent(HoverEvent.showEntity(
        Key.key("minecraft:player"),
        UUID.randomUUID(),
        Component.text("Steve the Builder")
    ));

/**
 * Objects that can be used as hover event sources
 */
interface HoverEventSource<V> {
    /**
     * Creates a hover event from this object
     * @return hover event sourced from this object
     */
    @Nullable HoverEvent<V> asHoverEvent();
    
    /**
     * Creates a hover event with specific action
     * @param action the hover action
     * @return hover event or null if not supported
     */
    @Nullable HoverEvent<V> asHoverEvent(HoverEvent.Action<V> action);
}

/**
 * Value interface for data components
 */
interface DataComponentValue extends Examinable {
    // Marker interface for data component values
}

/**
 * Registry for data component value converters
 */
class DataComponentValueConverterRegistry {
    /**
     * Converts a data component value to hover event content
     * @param value the data component value
     * @return hover event content or null
     */
    @Nullable Object convert(DataComponentValue value);
    
    /**
     * Registers a converter for a data component type
     * @param type the component type
     * @param converter the converter function
     */
    <T extends DataComponentValue> void register(Class<T> type, Function<T, ?> converter);
    
    /**
     * Gets the global converter registry
     * @return the global registry
     */
    static DataComponentValueConverterRegistry global();
}

// Combine click and hover for rich interactivity
Component interactiveButton = Component.text("[Click Here]")
    .color(NamedTextColor.GREEN)
    .decorate(TextDecoration.BOLD)
    .clickEvent(ClickEvent.runCommand("/shop"))
    .hoverEvent(HoverEvent.showText(
        Component.text("Click to open the shop!", NamedTextColor.YELLOW)
    ));

// Information with action
Component infoWithAction = Component.text("Player123")
    .color(NamedTextColor.BLUE)
    .clickEvent(ClickEvent.suggestCommand("/msg Player123 "))
    .hoverEvent(HoverEvent.showText(
        Component.text()
            .append(Component.text("Player123", NamedTextColor.BLUE, TextDecoration.BOLD))
            .appendNewline()
            .append(Component.text("Level: 25", NamedTextColor.GREEN))
            .appendNewline()
            .append(Component.text("Click to send message", NamedTextColor.GRAY, TextDecoration.ITALIC))
            .build()
    ));

// Apply events conditionally
Component conditionalComponent = Component.text("Action Button")
    .colorIf(canClick, NamedTextColor.GREEN, NamedTextColor.GRAY)
    .applyIf(canClick, component -> component
        .clickEvent(ClickEvent.runCommand("/action"))
        .hoverEvent(HoverEvent.showText(Component.text("Click to perform action")))
    )
    .applyIf(!canClick, component -> component
        .hoverEvent(HoverEvent.showText(Component.text("You cannot perform this action", NamedTextColor.RED)))
    );

// Helper methods for common event patterns
public static ClickEvent commandButton(String command) {
    return ClickEvent.runCommand("/" + command);
}

public static HoverEvent<Component> tooltip(String text) {
    return HoverEvent.showText(Component.text(text, NamedTextColor.YELLOW));
}

public static HoverEvent<Component> multilineTooltip(String... lines) {
    Component.Builder builder = Component.text();
    for (int i = 0; i < lines.length; i++) {
        if (i > 0) builder.appendNewline();
        builder.append(Component.text(lines[i]));
    }
    return HoverEvent.showText(builder.build());
}

// Usage
Component menuButton = Component.text("[Menu]")
    .clickEvent(commandButton("menu"))
    .hoverEvent(multilineTooltip(
        "Server Menu",
        "Click to open the main menu"
    ));