// Copyright 2019 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.accessibility.semantics;

using fuchsia.math;
using fuchsia.ui.views;

/// Maximum depth of the semantic tree.
const MAX_TREE_DEPTH uint64 = 256;

/// Maximum number of children for a node in the semantic tree.
const MAX_FAN_OUT uint64 = 20000;

/// Maximum number of semantic nodes that may be sent in a single update.
const MAX_NODES_PER_UPDATE uint64 = 2048;

/// Maximum size of a label string, in bytes.
const MAX_LABEL_SIZE uint64 = 16384;

/// Maximum size of a value string, in bytes.
const MAX_VALUE_SIZE uint64 = 16384;

/// Maximum size of a message string, in bytes.
const MAX_MESSAGE_SIZE uint64 = 16384;

/// An interface to manage connections with views for the purposes of gathering semantic information
/// about their current UI state.
///
/// The manager allows clients to register as a semantic provider for their view(s). In return the
/// semantics manager supplies an interface to update, commit and delete information from the
/// semantic tree for that view. If the semantic manager encounters an error, it will close the
/// channel, delete any associated data and rely on the client to re-register.
@discoverable
closed protocol SemanticsManager {
    strict RegisterViewForSemantics(resource struct {
        view_ref fuchsia.ui.views.ViewRef;
        listener client_end:SemanticListener;
        semantic_tree_request server_end:SemanticTree;
    });
};

/// Represents a Semantic Event that is fired on a Semantic Tree.
type SemanticEvent = strict union {
    1: announce AnnounceEvent;
};

/// An announce event is one where a message is sent to a Semantic Tree,
/// informing a change of some global state in the application. Because this
/// announcement can be disruptive to assistive technology, it should be used
/// sparingly.
type AnnounceEvent = table {
    /// A message describing the change in the application. This message is expected to be localized in the language that the application is in.
    1: message string:MAX_MESSAGE_SIZE;
};

/// Interface to update the semantic tree for a particular view. Nodes can be added, updated or
/// deleted. Because the size of an update may exceed FIDL transfer limits, clients are responsible
/// for breaking up changes into multiple update and delete calls that conform to these limits. The
/// commit function must always be called at the end of a full update push to signal the end of an
/// update.
///
/// The client may make several calls to UpdateSemanticNodes(...) or DeleteSemanticNodes(...)
/// before calling CommitUpdates(), and must wait for the semantics manager to reply to the
/// CommitUpdates() method to know whether an update has been processed. This allows the client to
/// break up a set of changes (e.g. a re-computed semantic tree) to the semantic tree into
/// FIDL-compatible chunks, but commit them all at once.
///
/// If the semantics manager ever receives inconsistent state from the client, such as an
/// invalid tree or unrecognized parent node id, the server will close the channel. The client is
/// responsible for reconnecting and re-sending its state from scratch.
closed protocol SemanticTree {

    /// Sends new/updated nodes to the root to add to the cache on the next commit.
    strict UpdateSemanticNodes(struct {
        nodes vector<Node>:MAX_NODES_PER_UPDATE;
    });

    /// Tells the root to remove nodes with node_ids from the semantic tree on the next commit.
    strict DeleteSemanticNodes(struct {
        node_ids vector<uint32>:MAX_NODES_PER_UPDATE;
    });

    /// Commits pending changes to node tree associated with the view using UpdateSemanticNodes and
    /// DeleteSemanticNodes. Updates are processed in the order in which they are received. If the
    /// committed updates result in an ill-formed tree (for example a missing root node or a cycle)
    /// the semantic manager will close the channel.
    strict CommitUpdates() -> ();

    /// Sends a Semantic Event related to this tree. This applies immediately
    /// and does not wait for CommitUpdates(). It is the caller's
    /// responsibility to fire events on nodes that have been already commited.
    /// The return callback is invoked to acknowledge that the event was received.
    strict SendSemanticEvent(struct {
        semantic_event SemanticEvent;
    }) -> ();
};

/// Results of hit testing on a view's semantic tree which is implemented by
/// Runtimes(like Flutter/Chrome) and sent to Accessibility.
type Hit = table {
    /// Unique ID that represents a node in a particular UI.
    /// Zero is assumed to be the root node and the only entry point to the tree.
    /// node_id will not be filled when there is no hit.
    1: node_id uint32;

    /// The ordered list of node ids which represent path from root node to the hit node.
    2: path_from_root vector<uint32>:MAX_TREE_DEPTH;
};

/// A semantic provider is the client-side interface that the manager can use to enable or disable
/// semantic updates, and to ask clients to perform accessibility actions.
closed protocol SemanticListener {
    /// Asks the semantics provider to perform an accessibility action on the
    /// node with node id in the front-end.
    strict OnAccessibilityActionRequested(struct {
        node_id uint32;
        action Action;
    }) -> (struct {
        handled bool;
    });

    /// Asks the semantics provider to perform hit testing and return the result.
    strict HitTest(struct {
        local_point fuchsia.math.PointF;
    }) -> (struct {
        result Hit;
    });

    /// Callback telling the client whether or not to send updates to the semantic tree.
    /// The semantics manager will clear all state when this is called with updates_enabled = false.
    /// When called with updates_enabled = true, the client should sent the full state of the
    /// current semantic tree.
    strict OnSemanticsModeChanged(struct {
        updates_enabled bool;
    }) -> ();
};