// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.ui.test.conformance;

using fuchsia.math;
using fuchsia.ui.test.input;
using fuchsia.ui.views;
using fuchsia.ui.composition;
using fuchsia.ui.input3;

/// Maximum number of filled rects a client can draw in a given image.
const MAX_RECTS_PER_IMAGE uint32 = 1024;

/// Result of a puppet operation.
type Result = flexible enum {
    /// The puppet does not support the requested operation. This situation
    /// may arise in several cases:
    ///
    /// 1. The runtime supports this operation, but the puppet has not yet
    ///    implemented it.
    /// 2. The runtime does not support this operation, and the puppet will
    ///    never implement it.
    /// 3. The puppet does not recognize this operation; this case may arise
    ///    when new fields or methods are added to the Puppet protocol.
    ///
    /// A test will pass if the puppet returns UNSUPPORTED from any requested
    /// operations.
    UNSUPPORTED = 0;

    /// The puppet successfully completed the requested operation.
    SUCCESS = 1;

    /// The puppet failed to complete the requested operation.
    ERROR = 2;
};

/// Defines the color of a piece of visual content.
///
/// We limit the palette to fully saturated colors to simplify verification
/// with screenshots.
type Color = flexible enum {
    /// 0x000000
    BLACK = 1;

    /// 0xFF0000
    RED = 2;

    /// 0x00FF00
    GREEN = 3;

    /// 0x0000FF
    BLUE = 4;

    /// 0xFFFF00
    YELLOW = 5;

    /// 0xFF00FF
    MAGENTA = 6;

    /// 0x00FFFF
    CYAN = 7;

    /// 0xFFFFFF
    WHITE = 8;
};

/// Defines the size and position of a piece of graphical content.
///
/// The bounds of the content are assumed to be rectangular.
type ContentBounds = table {
    /// The size of the content, defined in its parent view's coordinate space.
    ///
    /// For example, a parent view with size 1280x800 is assumed to have a
    /// useful coordinate space from (0, 0) to (1280, 800). A piece of content
    /// that's one-fourth the area of the parent view would have size 640x400.
    1: size fuchsia.math.SizeU;

    /// The location of the top-left corner of the content's origin, defined in
    /// the parent view's coordinate space.
    ///
    /// Returning to the example above, we could position the content to cover
    /// the bottom-right quadrant of the parent by assigning an origin of
    /// (640, 400).
    2: origin fuchsia.math.Vec;
};

/// Describes a rectangle with a solid, monochrome fill.
type FilledRect = table {
    /// The color of the rectangle's fill.
    1: color Color;

    /// The rectangle's bounds, defined in the parent view's coordinate space.
    2: bounds ContentBounds;
};

/// Describes an embedded view.
type EmbeddedViewProperties = table {
    /// The embedded view's bounds, defined in the parent view's coordinate
    /// space.
    1: bounds ContentBounds;
};

/// Describes a piece of visual content.
type ImageProperties = table {
    /// The image's bounds, defined in the parent view's coordinate space.
    1: bounds ContentBounds;

    /// Describes the contents of the image. Rects are considered to be in
    /// reverse z-order, i.e. successive elements are drawn on top of their
    /// predecessors.
    2: filled_rects vector<FilledRect>:MAX_RECTS_PER_IMAGE;
};

/// ******************************* PLEASE READ *******************************
///
/// A tool to help developers write generalizable tests against a well-defined
/// client application ("the puppet"). This API is not intended to cover every
/// possible UI platform API use case.
///
/// TOPOLOGY
///
/// Each puppet is assumed to own exactly one view.
///
/// Each piece of content added is assumed to be a "direct child" of this view;
/// and a sibling of the rest of the view's contents. In other words, all
/// embedded views, filled rects, etc. are considered to have "sibling" semantics;
/// for example, repositioning or resizing one piece of content should not
/// reposition/resize any other piece of content.
///
/// Z-ORDERING
///
/// The contents of a puppet's view are z-ordered according to the order in which
/// they were created. The first piece of content created appears at the "bottom",
/// and the last piece of content created appears at the "top".
///
/// IDS
///
/// All ids must be globally unique, e.g. a "filled rect" id belongs to the same
/// id space as an "embedded view" id.
///
/// SYNCHRONIZATION
///
/// All methods should block until the frame containing the requested changes has
/// rendered to the display, if a new frame is required.
///
/// RETURN VALUES
///
/// See documentation on the `Result` enum above.
///
/// UNKNOWN INTERACTIONS
///
/// Puppet implementations may live outside of fuchsia.git, so they will encounter
/// unknown methods and/or fields any time we extend the puppet API. In these cases,
/// the puppet should always return `UNSUPPORTED`.
closed protocol Puppet {
    // Graphics methods

    /// Embeds a view owned elsewhere.
    ///
    /// The puppet should create a (ViewportCreationToken, ViewCreationToken) pair
    /// and use the former to create a viewport with the specified `properties`.
    /// Once the puppet has presented a frame containing the new viewport, it should
    /// return the view creation token to the caller.
    strict EmbedRemoteView(table {
        1: id uint64;
        2: properties EmbeddedViewProperties;
    }) -> (resource table {
        1: result Result;
        2: view_creation_token fuchsia.ui.views.ViewCreationToken;
    });

    /// Updates the properties of an embedded view.
    strict SetEmbeddedViewProperties(table {
        1: id uint64;
        2: properties EmbeddedViewProperties;
    }) -> (table {
        1: result Result;
    });

    /// Draws an image composed of solid, monochrome-filled rectangles.
    strict DrawImage(table {
        1: id uint64;
        2: properties ImageProperties;
    }) -> (table {
        1: result Result;
    });

    /// Updates the properties of an image.
    strict SetImageProperties(table {
        1: id uint64;
        2: properties ImageProperties;
    }) -> (table {
        1: result Result;
    });
};

/// Used to create a puppet instance.
type PuppetCreationArgs = resource table {
    1: server_end server_end:<Puppet>;
    2: view_token fuchsia.ui.views.ViewCreationToken;
    3: touch_listener client_end:fuchsia.ui.test.input.TouchInputListener;
    4: mouse_listener client_end:fuchsia.ui.test.input.MouseInputListener;
    5: keyboard_listener client_end:fuchsia.ui.test.input.KeyboardInputListener;
    6: flatland_client client_end:fuchsia.ui.composition.Flatland;
    7: keyboard_client client_end:fuchsia.ui.input3.Keyboard;
    8: device_pixel_ratio float32;
    9: focuser server_end:fuchsia.ui.views.Focuser;
};

/// A helper to spawn a puppet instance, which will own a view created with a specific
/// token.
@discoverable
closed protocol PuppetFactory {
    /// Spawns a puppet instance, which will own a view created using `view_token`, and
    /// binds `puppet_server` to it.
    strict Create(PuppetCreationArgs) -> (resource table {
        1: result Result;
        /// view_ref of the created view.
        2: view_ref fuchsia.ui.views.ViewRef;
    });
};