Core Framework

/**
 * Base class for all Vaadin UI components.
 * Provides common functionality for visibility, styling, element access, and UI access.
 */
abstract class Component {
    /**
     * Sets the component's id attribute
     * @param id - Component identifier
     */
    void setId(String id);

    /**
     * Gets the component's id
     * @return Optional containing id if set
     */
    Optional<String> getId();

    /**
     * Sets whether component is visible
     * @param visible - true to show, false to hide
     */
    void setVisible(boolean visible);

    /**
     * Checks if component is visible
     * @return true if visible
     */
    boolean isVisible();

    /**
     * Adds CSS class name to component
     * @param className - CSS class name
     */
    void addClassName(String className);

    /**
     * Removes CSS class name from component
     * @param className - CSS class name to remove
     */
    void removeClassName(String className);

    /**
     * Sets CSS class names, replacing previous classes
     * @param className - CSS class name(s)
     */
    void setClassName(String className);

    /**
     * Gets underlying DOM element
     * @return Element instance
     */
    Element getElement();

    /**
     * Gets UI instance this component belongs to
     * @return Optional containing UI if attached
     */
    Optional<UI> getUI();

    /**
     * Adds listener for attach events
     * @param listener - Attach event listener
     * @return Registration for removing listener
     */
    Registration addAttachListener(ComponentEventListener<AttachEvent> listener);

    /**
     * Adds listener for detach events
     * @param listener - Detach event listener
     * @return Registration for removing listener
     */
    Registration addDetachListener(ComponentEventListener<DetachEvent> listener);
}

/**
 * Base class for custom composite components
 */
abstract class Composite<T extends Component> extends Component {
    /**
     * Gets the composed content component
     * @return Content component
     */
    protected abstract T initContent();

    /**
     * Gets the content component
     * @return Content component instance
     */
    protected T getContent();
}

/**
 * Interface for components that can contain other components
 */
interface HasComponents {
    /**
     * Adds components to this container
     * @param components - Components to add
     */
    void add(Component... components);

    /**
     * Removes components from this container
     * @param components - Components to remove
     */
    void remove(Component... components);

    /**
     * Removes all components from this container
     */
    void removeAll();

    /**
     * Adds component at specific index
     * @param index - Index position
     * @param component - Component to add
     */
    void addComponentAtIndex(int index, Component component);
}

/**
 * Interface for components with styling capabilities
 */
interface HasStyle {
    /**
     * Adds CSS class name(s)
     * @param className - CSS class name(s)
     */
    void addClassName(String className);

    /**
     * Removes CSS class name(s)
     * @param className - CSS class name(s)
     */
    void removeClassName(String className);

    /**
     * Sets CSS class name(s), replacing previous
     * @param className - CSS class name(s)
     */
    void setClassName(String className);

    /**
     * Gets style object for inline styles
     * @return Style instance
     */
    Style getStyle();
}

/**
 * Interface for components with size configuration
 */
interface HasSize {
    /**
     * Sets width
     * @param width - Width value with unit (e.g., "200px", "50%")
     */
    void setWidth(String width);

    /**
     * Sets height
     * @param height - Height value with unit
     */
    void setHeight(String height);

    /**
     * Sets min width
     * @param minWidth - Minimum width value with unit
     */
    void setMinWidth(String minWidth);

    /**
     * Sets max width
     * @param maxWidth - Maximum width value with unit
     */
    void setMaxWidth(String maxWidth);

    /**
     * Sets width to 100%
     */
    void setWidthFull();

    /**
     * Sets height to 100%
     */
    void setHeightFull();

    /**
     * Sets both width and height to 100%
     */
    void setSizeFull();
}

/**
 * Interface for components that can be enabled/disabled
 */
interface HasEnabled {
    /**
     * Sets whether component is enabled
     * @param enabled - true to enable, false to disable
     */
    void setEnabled(boolean enabled);

    /**
     * Checks if component is enabled
     * @return true if enabled
     */
    boolean isEnabled();
}

/**
 * Interface for input components with values
 */
interface HasValue<E extends HasValueChangeEvent<V>, V> extends HasEnabled {
    /**
     * Sets the value
     * @param value - New value
     */
    void setValue(V value);

    /**
     * Gets the current value
     * @return Current value
     */
    V getValue();

    /**
     * Adds value change listener
     * @param listener - Value change listener
     * @return Registration for removing listener
     */
    Registration addValueChangeListener(ValueChangeListener<? super E> listener);

    /**
     * Sets whether component is read-only
     * @param readOnly - true for read-only
     */
    void setReadOnly(boolean readOnly);

    /**
     * Checks if component is read-only
     * @return true if read-only
     */
    boolean isReadOnly();

    /**
     * Sets whether component is required
     * @param required - true if required
     */
    void setRequiredIndicatorVisible(boolean required);
}

/**
 * Annotation to mark a class as a routable view
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Route {
    /**
     * URL path for this route
     * @return URL path (empty string for root)
     */
    String value() default "";

    /**
     * Parent layout class
     * @return Layout class
     */
    Class<? extends RouterLayout> layout() default UI.class;
}

/**
 * Annotation to set page title
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface PageTitle {
    /**
     * Page title text
     * @return Title string
     */
    String value();
}

/**
 * Annotation for route prefix on layouts
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface RoutePrefix {
    /**
     * URL prefix for all child routes
     * @return URL prefix
     */
    String value();
}

/**
 * Annotation for menu integration (Vaadin 24+)
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Menu {
    /**
     * Menu item title
     * @return Menu title
     */
    String title() default "";

    /**
     * Menu item order
     * @return Order value (lower values first)
     */
    double order() default Integer.MAX_VALUE;
}

/**
 * Component for navigation links
 */
class RouterLink extends Component {
    /**
     * Creates router link
     */
    RouterLink();

    /**
     * Creates router link with text and target
     * @param text - Link text
     * @param navigationTarget - Target view class
     */
    RouterLink(String text, Class<? extends Component> navigationTarget);

    /**
     * Sets link text
     * @param text - Link text
     */
    void setText(String text);

    /**
     * Sets navigation target
     * @param navigationTarget - Target view class
     */
    void setRoute(Class<? extends Component> navigationTarget);
}

/**
 * Interface for route enter lifecycle
 */
interface BeforeEnterObserver {
    /**
     * Called before entering a route
     * @param event - Before enter event
     */
    void beforeEnter(BeforeEnterEvent event);
}

/**
 * Event fired before entering a route
 */
class BeforeEnterEvent {
    /**
     * Gets navigation location
     * @return Location instance
     */
    Location getLocation();

    /**
     * Reroutes to different view
     * @param navigationTarget - Target view class
     */
    void rerouteTo(Class<? extends Component> navigationTarget);

    /**
     * Forwards to error view
     * @param exception - Exception to display
     */
    void rerouteToError(Exception exception);
}

/**
 * Interface for route leave lifecycle
 */
interface BeforeLeaveObserver {
    /**
     * Called before leaving a route
     * @param event - Before leave event
     */
    void beforeLeave(BeforeLeaveEvent event);
}

/**
 * Event fired before leaving a route
 */
class BeforeLeaveEvent {
    /**
     * Postpones navigation
     * @return ContinueNavigationAction for resuming
     */
    ContinueNavigationAction postpone();
}

/**
 * Interface for routes with URL parameters
 */
interface HasUrlParameter<T> {
    /**
     * Sets parameters from URL
     * @param event - Before enter event
     * @param parameter - URL parameter
     */
    void setParameter(BeforeEvent event, T parameter);
}

/**
 * Utility for query parameters
 */
class QueryParameters {
    /**
     * Gets query parameters from map
     * @param parameters - Parameter map
     * @return QueryParameters instance
     */
    static QueryParameters simple(Map<String, String> parameters);

    /**
     * Gets parameter values
     * @param name - Parameter name
     * @return List of values
     */
    List<String> getParameters(String name);
}

/**
 * Main UI class
 */
class UI extends Component {
    /**
     * Gets current UI instance
     * @return Optional containing current UI
     */
    static Optional<UI> getCurrent();

    /**
     * Navigates to view
     * @param navigationTarget - Target view class
     */
    void navigate(Class<? extends Component> navigationTarget);

    /**
     * Navigates to view with parameters
     * @param navigationTarget - Target view class
     * @param parameter - URL parameter
     */
    <T> void navigate(Class<? extends Component> navigationTarget, T parameter);

    /**
     * Navigates to URL
     * @param url - URL string
     */
    void navigate(String url);

    /**
     * Gets page object
     * @return Page instance
     */
    Page getPage();
}

// Basic view with routing
@Route("dashboard")
@PageTitle("Dashboard")
public class DashboardView extends VerticalLayout {
    public DashboardView() {
        add(new H1("Dashboard"));
        // Add components
    }
}

// Navigation with RouterLink
VerticalLayout menu = new VerticalLayout();
menu.add(
    new RouterLink("Home", HomeView.class),
    new RouterLink("Products", ProductsView.class),
    new RouterLink("About", AboutView.class)
);

// Programmatic navigation
Button goToDetails = new Button("View Details", event -> {
    UI.getCurrent().navigate(DetailsView.class);
});

// With parameters
Button goToProduct = new Button("View Product", event -> {
    UI.getCurrent().navigate(ProductView.class, productId);
});

// Route lifecycle hooks
@Route("editor")
public class EditorView extends VerticalLayout
        implements BeforeLeaveObserver {

    @Override
    public void beforeLeave(BeforeLeaveEvent event) {
        if (hasUnsavedChanges()) {
            event.postpone();
            ConfirmDialog dialog = new ConfirmDialog(
                "Unsaved Changes",
                "Do you want to discard changes?",
                "Discard",
                confirmEvent -> event.getContinueNavigationAction().proceed(),
                "Cancel",
                cancelEvent -> {}
            );
            dialog.open();
        }
    }
}

// Custom composite component
public class UserCard extends Composite<Div> {
    private final Avatar avatar = new Avatar();
    private final Span name = new Span();
    private final Span email = new Span();

    @Override
    protected Div initContent() {
        Div card = new Div();
        card.addClassName("user-card");
        card.add(avatar, name, email);
        return card;
    }

    public void setUser(User user) {
        avatar.setName(user.getName());
        name.setText(user.getName());
        email.setText(user.getEmail());
    }
}

/**
 * Main Vaadin servlet
 */
class VaadinServlet extends HttpServlet {
    /**
     * Creates Vaadin servlet
     */
    VaadinServlet();
}

/**
 * Vaadin service singleton
 */
class VaadinService {
    /**
     * Gets current service instance
     * @return Current VaadinService
     */
    static VaadinService getCurrent();
}

/**
 * User session
 */
class VaadinSession {
    /**
     * Gets current session
     * @return Optional containing current session
     */
    static Optional<VaadinSession> getCurrent();

    /**
     * Sets session attribute
     * @param name - Attribute name
     * @param value - Attribute value
     */
    void setAttribute(String name, Object value);

    /**
     * Gets session attribute
     * @param name - Attribute name
     * @return Attribute value
     */
    Object getAttribute(String name);
}

/**
 * Annotation for Progressive Web App configuration
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface PWA {
    /**
     * Application name
     * @return App name
     */
    String name();

    /**
     * Short application name
     * @return Short name
     */
    String shortName() default "";

    /**
     * App description
     * @return Description
     */
    String description() default "";
}

/**
 * Interface for application shell configuration
 */
interface AppShellConfigurator {
}

/**
 * Annotation for server push configuration
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Push {
    /**
     * Push mode
     * @return PushMode enum value
     */
    PushMode value() default PushMode.AUTOMATIC;
}

enum PushMode {
    DISABLED, MANUAL, AUTOMATIC
}

/**
 * Annotation for theme selection
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Theme {
    /**
     * Theme name or class
     * @return Theme identifier
     */
    String value() default "";

    /**
     * Theme variant (e.g., "dark")
     * @return Variant name
     */
    String variant() default "";
}

// Progressive Web App configuration
import com.vaadin.flow.component.page.AppShellConfigurator;
import com.vaadin.flow.server.PWA;
import com.vaadin.flow.theme.Theme;
import com.vaadin.flow.theme.lumo.Lumo;

@Theme(value = Lumo.class)
@PWA(
    name = "My Application",
    shortName = "MyApp",
    description = "My awesome Vaadin application"
)
public class AppShell implements AppShellConfigurator {
}

// Session attributes
VaadinSession.getCurrent().ifPresent(session -> {
    session.setAttribute("userId", user.getId());
    Object userId = session.getAttribute("userId");
});

/**
 * Represents the browser page
 */
class Page {
    /**
     * Executes JavaScript in browser
     * @param expression - JavaScript expression
     * @return PendingJavaScriptResult for handling result
     */
    PendingJavaScriptResult executeJs(String expression, Serializable... parameters);

    /**
     * Sets page title
     * @param title - Page title
     */
    void setTitle(String title);

    /**
     * Opens URL in new window/tab
     * @param url - URL to open
     */
    void open(String url);

    /**
     * Adds browser window resize listener
     * @param listener - Resize listener
     * @return Registration for removing listener
     */
    Registration addBrowserWindowResizeListener(ComponentEventListener<BrowserWindowResizeEvent> listener);
}

/**
 * Result of JavaScript execution
 */
interface PendingJavaScriptResult {
    /**
     * Handles result as string
     * @param handler - Result handler
     */
    void then(SerializableConsumer<String> handler);

    /**
     * Handles result as JSON
     * @param handler - Result handler
     * @param errorHandler - Error handler
     */
    void then(SerializableConsumer<JsonValue> handler, SerializableConsumer<String> errorHandler);
}

Page page = UI.getCurrent().getPage();

// Simple execution
page.executeJs("console.log('Hello from Java')");

// With parameters
page.executeJs("console.log($0)", "Parameter value");

// Handle result
page.executeJs("return window.innerWidth")
    .then(Integer.class, width -> {
        Notification.show("Window width: " + width);
    });

// Set page title
page.setTitle("My Application - Dashboard");

// Open URL in new window
page.open("https://vaadin.com");

/**
 * Annotation for importing CSS files
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface CssImport {
    /**
     * CSS file path
     * @return Path to CSS file
     */
    String value();

    /**
     * Theme for CSS (e.g., "lumo")
     * @return Theme name
     */
    String themeFor() default "";

    /**
     * Include parameter for conditional imports
     * @return Include parameter
     */
    String include() default "";
}

/**
 * Annotation for importing JavaScript modules
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface JsModule {
    /**
     * JavaScript module path
     * @return Path to JS module
     */
    String value();
}

/**
 * Annotation for NPM package dependencies
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface NpmPackage {
    /**
     * NPM package name
     * @return Package name
     */
    String value();

    /**
     * Package version
     * @return Version string
     */
    String version();
}

// Custom CSS import
@Route("styled")
@CssImport("./styles/custom-styles.css")
public class StyledView extends VerticalLayout {
    // View implementation
}

// Scoped CSS for component
@CssImport(
    value = "./styles/grid-custom.css",
    themeFor = "vaadin-grid"
)
public class GridView extends VerticalLayout {
    // Grid with custom styling
}

// JavaScript module import
@Route("custom")
@JsModule("./scripts/custom-component.js")
public class CustomView extends VerticalLayout {
}

// NPM package dependency
@NpmPackage(value = "lodash", version = "^4.17.21")
public class UtilityView extends VerticalLayout {
}