// 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.ui.gfx;

/// Max number of elements in a semantic set.
const uint32 MAX_SET_ELEMENTS = 100;

/// Represents actions that can be applied to Nodes.
enum Action {
    /// The default action associated with the element.
    DEFAULT = 1;
    /// The secondary action associated with the element. This may correspond to a long press
    /// (touchscreens) or right click (mouse).
    SECONDARY = 2;
    /// Set (input/non-accessibility) focus on this element.
    SET_FOCUS = 3;
    /// Set the element's value.
    SET_VALUE = 4;
    /// Scroll node to make it visible.
    SHOW_ON_SCREEN = 5;
    /// Decrement a slider by one step value. The step size is defined by the
    /// owner of the semantic node that executes this action. For example, a
    /// volume slider may want to make steps 1, 2, 3, while a time slider may
    /// want to skip 30 seconds each step change.
    DECREMENT = 6;
    /// Increment a slider by one step value. The step size is defined by the
    /// owner of the semantic node that executes this action. For example, a
    /// volume slider may want to make steps 1, 2, 3, while a time slider may
    /// want to skip 30 seconds each step change.
    INCREMENT = 7;
};

/// Represents a role of an element on a UI.
enum Role {
    /// Role used to represent elements which role is not currently supported.
    UNKNOWN = 1;
    /// Something on screen that can be clicked/activated, that has a single function.
    BUTTON = 2;
    /// Header text, e.g. something tagged <h1> in HTML.
    HEADER = 3;
    /// An image or graphic.
    IMAGE = 4;
    /// A field containing text that is not a header.
    TEXT_FIELD = 5;
    /// A slider, e.g. a volume slider or a time slider of a video.
    SLIDER = 6;
    /// A link, e.g. a link on a webpage.
    LINK = 7;
    /// A check box that can be toggled.
    CHECK_BOX = 8;
    /// A radio button that selects an option among a group of options.
    RADIO_BUTTON = 9;

    /// Role used to represent lists.
    LIST = 10;

    /// Role used to represent a list marker (e.g. a bullet point, number, roman
    /// numeral, etc.).
    LIST_ELEMENT_MARKER = 12;

    /// Role used to represent immutable text.
    STATIC_TEXT = 13;

    /// Role used to represent toggle switch.
    TOGGLE_SWITCH = 14;

    /// Role used to represent a table of elements.
    TABLE = 15;

    /// Role used to represent a grid. For example, an element with the
    /// aria-grid role.
    GRID = 16;

    /// Role used to represent the row of a table.
    TABLE_ROW = 17;

    /// Role used to represent the cell of a table or grid.
    CELL = 18;

    /// Role used to represent a column header. For example, an element with
    /// the html tag <th>.
    COLUMN_HEADER = 19;

    /// Role used to represent an aria-rowgroup-like element.
    ROW_GROUP = 20;

    /// Role used to represent a paragraph of text.
    PARAGRAPH = 21;
};

/// The possible origins of a label.
enum LabelOrigin {
    /// The node does not have a label yet.
    UNITIALIZED = 1;
    /// An attribute of this element in the runtime UI explicitly sets its
    /// label. For example, an element with aria-label.
    ATTRIBUTE = 2;
    /// An attribute of this element in the runtime UI explicitly sets its
    /// label to be empty.
    ATTRIBUTE_EMPTY = 3;
    /// This label serves as the caption for a table-like element. Because some
    /// assistive technology have special modes to deal with tables, a runtime
    /// should mark its label with this type of origin so that users know what
    /// the table is about when they navigate in the table mode. For example,
    /// a <caption> html tag sets the label.
    CAPTION = 4;
    /// This node receives its label from the contents present in the
    /// application. For example, text from a web page becomes the label of
    /// this node.
    CONTENTS = 5;
    /// An element that can receive user entered value and has a suggested
    /// input. For example, the placeholder attribute on an html input field.
    PLACEHOLDER = 6;
    /// Another element provides the label for this element. For example, via
    /// aria-labeledby.
    RELATED_ELEMENT = 7;
    /// This element's label is represented by a visual tooltip. For example,
    /// as if from a <title> html tag.
    TITLE = 8;
    /// The label comes from an user-entered value.
    VALUE = 9;
};

/// Slider / range control attributes.
table RangeAttributes {
    /// The minimum value a range control element can take.
    1: float32 min_value;
    /// The maximum value a range control element can take.
    2: float32 max_value;
    /// The step delta the element applies when the action DECREMENT or
    /// INCREMENT are invoked.
    3: float32 step_delta;
};

/// Set attributes that control how an element is connected to others in the
/// same set. For example, a group of radio buttons in html containing the same
/// name attribute are part of the same set.
table SetAttributes {
    /// Size of the set.
    1: uint32 size;
    /// Element index in the set, starting from one.
    2: uint32 index;
    /// Node ids of other elements in this set.
    3: vector<uint32>:MAX_SET_ELEMENTS set_element_ids;
};

/// Attributes that control how a cell inside of a table behaves.
table TableAttributes {
    /// The number of columns this table cell spans.
    1: uint32 column_span;
    /// The number of rows this table cell spans.
    2: uint32 row_span;
};

/// An attribute is an essential property to describe an element. Unlike states, attributes do not
/// change over the life of an element.
/// Example: A button with a label attribute 'ok' should never change to 'cancel', as this is not
/// the same element.
table Attributes {
    /// The primary label for an element. If longer than MAX_LABEL_SIZE the client is responsible
    /// for truncating the label.
    1: string:MAX_LABEL_SIZE label;

    /// The secondary label for an element. If longer than MAX_LABEL_SIZE the client is responsible
    /// for truncating the label.
    2: string:MAX_LABEL_SIZE secondary_label;

    /// A description of what the secondary action on a node (equivalent to long press or right click) should do.
    3: string:MAX_LABEL_SIZE secondary_action_description;

    /// The range attributes are filled if the element is a slider / a range
    /// control.
    4: RangeAttributes range;

    /// Set attributes are filled if the element is part of some type of set.
    /// For example, radio buttons that are related are part of the same set.
    5: SetAttributes set;

    /// The list attributes are filled iff the node is a list.
    /// Note that only the size and set_element_ids may be filled for a list node.
    6: SetAttributes list_attributes;

    /// The list element attributes are filled iff the node is a child of a list node.
    7: SetAttributes list_element_attributes;

    /// The hierarchical level of an element. For example, a header can be of
    /// level 1 to 6 in html or markdown.
    8: uint32 hierarchical_level;

    /// The table attributes are filled when the element is a cell.
    9: TableAttributes table_attributes;

    /// The origin of the label of this element.
    10: LabelOrigin label_origin;

    /// Whether the element is part of a virtual keyboard. For example, a key
    /// on an onscreen keyboard.
    11: bool is_keyboard_key;
};

/// Represents the state of a UI checkbox.
enum CheckedState {
    /// Used when no data is entered or the element is not a check box.
    NONE = 1;
    /// Checked
    CHECKED = 2;
    /// Unchecked
    UNCHECKED = 3;
    /// Indeterminate state
    MIXED = 4;
};

/// Represents the state of a UI toggle switch.
enum ToggledState {
    /// Toggle switch is on.
    ON = 1;
    /// Toggle switch is off.
    OFF = 2;
    /// Toggle switch is in Indeterminate state.
    INDETERMINATE = 3;
};

/// A state is a dynamic property of an element that may change in response to
/// user action or automated processes. Thus, they are different from attributes
/// in an important point, which is frequency of change.
table States {
    /// DEPRECATED
    1: bool checked;

    /// State of a checkbox.
    /// This field is mutually exclusive with ToggledState.
    2: CheckedState checked_state;

    /// Whether the element is currently selected.
    3: bool selected;

    /// Whether the element is currently hidden or marked invisible by the framework.
    4: bool hidden;

    /// The user-entered value of the element, if applicable. If longer than MAX_VALUE_SIZE the
    /// client is responsible for truncating.
    5: string:MAX_VALUE_SIZE value;

    /// If the element is a slider or a range control, this field contains the
    /// current value. Note that this is not the same as the value field above,
    /// as this is generated by the client and just adjusted by the user.
    6: float32 range_value;

    // If the element is a scrollable viewport, this field contains the x and
    // y offsets within this node's coordinate space to apply to the children.
    // This offsetting is used to position the children within the viewport to
    // reflect the current scrolling of the element.   There are no constraints
    // on these values other than they must be finite.
    7: fuchsia.ui.gfx.vec2 viewport_offset;

    /// State of a toggle switch.
    /// This field must only be set if the element is a toggle switch element
    /// and is mutually exclusive with CheckedState.
    8: ToggledState toggled_state;

    /// Whether this element is focusable in the UI. Note that this is not the
    /// a11y focus, but the application focus.
    9: bool focusable;
};

/// The Node represents a semantic element on an interface. This may
/// be a button, a text field, a checkbox or any element that has a relevant
/// semantic meaning so that assistive technology can understand the current UI.
table Node {
    /// 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.
    /// No forest is allowed.
    1: uint32 node_id;

    /// Role of this element, e.g. button, checkbox, etc.
    2: Role role;

    /// A table of states of this object, e.g. checked, editable, etc.
    3: States states;

    /// A table of attributes of this node.
    4: Attributes attributes;

    /// A list of actions that can be performed on this node.
    5: vector<Action>:100 actions;

    /// The list of child IDs of this node, in traversal order. Runtimes supplying semantic tree
    /// information are responsible for ensuring the tree does not contain cycles. Each node may
    /// have only one parent.
    6: vector<uint32>:MAX_FAN_OUT child_ids;

    /// Local bounding box of this element.
    7: fuchsia.ui.gfx.BoundingBox location;

    /// Transform from this node's coordinate space to its container's space. 4x4 for compatibility
    /// with scenic.  This matrix is required to have the form
    ///
    ///  [ Sx   0    0    Tx ]
    ///  [ 0    Sy   0    Ty ]
    ///  [ 0    0    Sz   Tz ]
    ///  [ 0    0    0    1  ]
    ///
    ///  where Sx, Sy, and Sz are scale factors and Tx, Ty, Tz are the translation factors for
    ///  the x, y, and z components
    8: fuchsia.ui.gfx.mat4 transform;

    /// Node ID of the ancestor of this node that is used as the target of |transform|.
    /// If not present, this defaults to this node's parent.
    9: uint32 container_id;
};